> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Uploads and downloads

> Move private object bytes through short-lived capabilities while keeping API authority tenant-scoped.

The API authorizes object access but does not proxy private file bytes. It returns short-lived, object-scoped URLs for direct transfer.

## Upload a knowledge document

<Steps>
  <Step title="Create pending metadata">
    Call `createKnowledgeDocument` with the file name, byte size, media type, and display name. The response contains the pending document and an `upload` capability.
  </Step>

  <Step title="Upload bytes directly">
    Send the file to `upload.url` with the returned HTTP method and every header in `upload.headers`.

    ```bash theme={null}
    curl --fail-with-body \
      --request PUT \
      --header "Content-Type: application/pdf" \
      --upload-file "operations-manual.pdf" \
      "${UPLOAD_URL}"
    ```

    Do not send your Arbol bearer token to the object URL. Use only the headers returned with the capability.
  </Step>

  <Step title="Complete ingestion">
    Before the capability and pending upload expire, call `completeKnowledgeDocument` for the document ID. Completion validates the object and starts indexing. Completion is idempotent by document ID.
  </Step>
</Steps>

The generated endpoint schema is authoritative for file-size and media-type limits.

## Download private content

Conversation media, knowledge source bytes, and retained evaluation artifacts use authorization operations that return a short-lived read URL. Fetch that URL without forwarding the Arbol bearer token.

<Info>
  Creating another download capability is safe, but each URL expires. Do not persist it as the durable identifier for an object.
</Info>

## Security rules

* Keep the returned capability URL out of logs and analytics.
* Never change the method, signed headers, or object key embedded in a capability.
* Use the API resource ID as the durable reference.
* Re-authorize immediately before a transfer rather than caching capabilities.