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

# Documents

> Upload, inspect, download, reprocess, and remove knowledge-base documents.

Documents supply the content AutoSage indexes for grounded retrieval. All endpoints are served under `/documents` and support API keys or signed-in user sessions.

<Note>
  All endpoints on this page are **\[User+Key]**. API keys need the corresponding `documents:read`, `documents:write`, or `documents:delete` scope.
</Note>

## Endpoints

| Method   | Path                         | Description                                 | Auth        |
| -------- | ---------------------------- | ------------------------------------------- | ----------- |
| `POST`   | `/documents/presign`         | Create a document and request an upload URL | \[User+Key] |
| `GET`    | `/documents/status`          | Check processing status                     | \[User+Key] |
| `GET`    | `/documents`                 | List documents in a knowledge base          | \[User+Key] |
| `POST`   | `/documents/upload-url`      | Ingest one web page                         | \[User+Key] |
| `POST`   | `/documents/upload-url-site` | Discover pages on a site                    | \[User+Key] |
| `GET`    | `/documents/:id`             | Get a document                              | \[User+Key] |
| `GET`    | `/documents/:id/download`    | Request a download URL                      | \[User+Key] |
| `DELETE` | `/documents/:id`             | Remove a document                           | \[User+Key] |
| `POST`   | `/documents/:id/reprocess`   | Process a document again                    | \[User+Key] |

## Request an upload URL

`POST /documents/presign`

Creates a document in `pending_upload` and returns a time-limited URL for uploading the raw bytes.

<ParamField body="kb_id" type="string" required>
  Knowledge base that will receive the document.
</ParamField>

<ParamField body="tenant_id" type="string" required>
  Tenant that owns the knowledge base. It must match the knowledge base's tenant.
</ParamField>

<ParamField body="filename" type="string" required>
  Original filename, including its extension.
</ParamField>

<ParamField body="mime_type" type="string" required>
  MIME type of the uploaded file.
</ParamField>

<ParamField body="size_bytes" type="number" required>
  File size in bytes. AutoSage checks document and storage quotas before returning an upload URL.
</ParamField>

```bash theme={null}
curl -X POST "$AUTOSAGE_URL/documents/presign" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_id": "KB_ID",
    "tenant_id": "TENANT_ID",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 482913
  }'
```

The response includes `document_id`, `upload_url`, `s3_key`, and `expires_at`. Treat `s3_key` as an opaque storage identifier.

### Upload the bytes

Upload the file directly to the returned `upload_url` before it expires:

```bash theme={null}
curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @handbook.pdf
```

Processing starts automatically after the upload completes. No additional API call is required.

## Check processing status

`GET /documents/status`

<ParamField query="document_id" type="string" required>
  Document ID returned by the presign request.
</ParamField>

```bash theme={null}
curl "$AUTOSAGE_URL/documents/status?document_id=DOCUMENT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

The response includes `status`, `is_processing`, timestamps, and document metadata.

| Status           | Meaning                                              |
| ---------------- | ---------------------------------------------------- |
| `pending_upload` | Waiting for file bytes.                              |
| `queued`         | Uploaded and waiting for processing.                 |
| `processing`     | Being parsed, chunked, embedded, and indexed.        |
| `processed`      | Searchable and ready for grounded answers.           |
| `failed`         | Processing did not complete.                         |
| `deleted`        | Removed from active document listings and retrieval. |

<Tip>
  Poll with backoff until the status is `processed` or `failed`. A document you later remove may be reported as `deleted`. See [Document ingestion](/developers/lifecycles/ingestion) for the complete lifecycle.
</Tip>

## List documents

`GET /documents`

<ParamField query="kb_id" type="string" required>
  Knowledge base whose active documents to list.
</ParamField>

```bash theme={null}
curl "$AUTOSAGE_URL/documents?kb_id=KB_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

Documents that have been removed are excluded.

## Ingest one web page

`POST /documents/upload-url`

Fetches one URL, converts its readable content into a document, and queues it for processing.

<ParamField body="kb_id" type="string" required>
  Destination knowledge base.
</ParamField>

<ParamField body="tenant_id" type="string" required>
  Owning tenant. It must match the knowledge base's tenant.
</ParamField>

<ParamField body="url" type="string" required>
  Page to ingest. AutoSage adds `https://` when the scheme is omitted.
</ParamField>

```bash theme={null}
curl -X POST "$AUTOSAGE_URL/documents/upload-url" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_id": "KB_ID",
    "tenant_id": "TENANT_ID",
    "url": "https://docs.example.com/getting-started"
  }'
```

## Discover site URLs

`POST /documents/upload-url-site`

Discovers up to 25 pages from a site. This endpoint returns URLs; ingest selected pages individually with `/documents/upload-url`.

<ParamField body="kb_id" type="string" required>
  Knowledge base used for access validation.
</ParamField>

<ParamField body="tenant_id" type="string" required>
  Owning tenant.
</ParamField>

<ParamField body="url" type="string" required>
  Site root to crawl.
</ParamField>

<ParamField body="include_subdomains" type="boolean">
  Include matching subdomains. Defaults to `false`.
</ParamField>

## Get a document

`GET /documents/:id`

Returns metadata for one document, including its processing state.

```bash theme={null}
curl "$AUTOSAGE_URL/documents/DOCUMENT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

## Request a download URL

`GET /documents/:id/download`

Returns a time-limited `download_url` for the original file, plus `filename` and `expires_at`.

## Remove a document

`DELETE /documents/:id`

Removes the document from search and begins cleanup of its stored file and indexed content.

<Warning>
  Removing a document is destructive. Clients should stop presenting it as searchable as soon as the request succeeds.
</Warning>

## Reprocess a document

`POST /documents/:id/reprocess`

Queues an existing document for processing again. This is useful after a `failed` status. Removed documents and derived text documents cannot be reprocessed independently.

<Tip>
  Full request and response schemas are available in the interactive explorer at `/swagger` on the API host.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Upload guide" icon="upload" href="/developers/guides/upload-documents">
    Implement the presigned upload flow in your application.
  </Card>

  <Card title="Ingestion lifecycle" icon="arrows-spin" href="/developers/lifecycles/ingestion">
    Understand processing stages, statuses, and quotas.
  </Card>

  <Card title="Knowledge bases" icon="database" href="/developers/api/knowledge-bases">
    Manage the knowledge base that owns these documents.
  </Card>

  <Card title="Retrieval lifecycle" icon="magnifying-glass" href="/developers/lifecycles/rag">
    See how processed content grounds answers.
  </Card>
</CardGroup>