Skip to main content

Upload files and ingest

A file-upload knowledge source takes files over the API. The upload stores them as pending documents and, when it can, starts indexing at once; the ingest route processes anything still pending; the document route shows each file's progress; and a search proves the content is live.

Who can use it: anyone holding an API key with the Documents scope for the upload and document routes and the Load knowledge graph scope for ingest; the sources list needs Knowledge search or Documents. Ingest also requires the key's owner to be the source's creator or to manage its access. Creating a source and uploading into it also require the key's owner to be allowed to create knowledge sources.

Prerequisites​

  • A file-upload knowledge source. Create it in the platform (Knowledge Sources in Studio, Add Source, then File Upload) or with POST /public/v1/sources using the file_upload connector type; the File Upload connector page in the help centre lists what it accepts.
  • Files of an accepted type, each within the size limit your administrator set for the tenant.

Upload, index and follow​

  1. Find the source id. GET /public/v1/sources lists the tenant's sources; pick the one whose connector_type is file_upload and keep its id.

  2. Upload the files as multipart form data in the files field, one part per file.

    curl -X POST "https://<your tenant host>/public/v1/sources/<source-id>/upload" \
    -H "Authorization: Bearer kapi_..." \
    -F "files=@quarterly-report.pdf" \
    -F "files=@vendor-policy.docx"

    The response lists what was stored under uploaded (each with its document id, filename, size_bytes and content_type), a count, any rejected files under failed with a reason, and two fields that tell you what happens next: sync_started says whether this request started the indexing run, and sync_note explains why not when it did not.

  3. Start indexing only if the upload did not. When sync_started is true, indexing is already under way. When it is false and sync_note says a sync was already running, that run will index the new files. When the note says indexing could not be started, call ingest:

    curl -X POST "https://<your tenant host>/public/v1/sources/<source-id>/ingest" \
    -H "Authorization: Bearer kapi_..."

    A 202 with status started carries the run_id; a 200 with no_pending_documents means there was nothing to do; a 409 means a sync is already running and names its run when it can.

  4. Follow each document. GET /public/v1/documents/<doc-id> returns the record: processing_status moves from pending through processing to completed, or ends as failed with processing_error, empty when no text could be indexed, or access_denied. chunk_count fills in as the document is indexed.

    import time, requests

    BASE = "https://<your tenant host>/public/v1"
    HEADERS = {"Authorization": "Bearer kapi_..."}

    with open("quarterly-report.pdf", "rb") as f:
    up = requests.post(f"{BASE}/sources/<source-id>/upload", headers=HEADERS,
    files=[("files", ("quarterly-report.pdf", f))]).json()
    if not up["sync_started"] and "could not be started" in (up.get("sync_note") or ""):
    requests.post(f"{BASE}/sources/<source-id>/ingest", headers=HEADERS)

    for doc in up["uploaded"]:
    while True:
    rec = requests.get(f"{BASE}/documents/{doc['id']}", headers=HEADERS).json()
    if rec["processing_status"] in ("completed", "failed", "empty", "access_denied"):
    print(doc["filename"], rec["processing_status"], rec.get("processing_error") or "")
    break
    time.sleep(5)
  5. Prove it. Search with source_ids limited to the source and a question the file answers; the hit's source names the document. See Search with citations.

Verify​

Each uploaded document reaches completed with a chunk_count above zero, and a search scoped to the source returns a passage from it. In the platform, the source's Documents tab lists the same files with the same status.

Troubleshooting​

  • Entries under failed: the reason starts with unsupported_type, too_large, empty_file or read_failed. Fix the file and upload it again; the others were stored.
  • 413: the request as a whole exceeds the tenant's limit. Upload fewer files per request.
  • 400 on upload or ingest: the source is not a file-upload source. Connector-backed sources sync on their own schedule; POST /public/v1/sources/<source-id>/sync starts one on demand.
  • 404 or 403 on ingest: the key's owner did not create the source and may not manage its access.
  • 409 on ingest: a sync is running; it picks up pending documents, so wait for it rather than retrying.
  • 502 on upload: nothing could be stored because the object store was unavailable. Tell your administrator.
  • A document stays pending: no run has picked it up. Check sync_started and sync_note from the upload, then call ingest.

Describes the platform as of .

Was this page helpful?