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

# Documents API

> Programmatically upload, list, inspect, rename, and delete documents in Space Uploaded Files

The Documents API allows developers to manage documents within Space Uploaded Files programmatically. This enables automated document ingestion from external CMSs, data pipelines, or document management systems.

## Base Path & Headers

All document endpoints require the `X-API-Key` authentication header:

```http theme={null}
X-API-Key: your_omnifact_api_key_here
```

***

## Health Check Ping

`GET /`

Verifies that the API service is online and accessible.

#### Example Request

```bash theme={null}
curl -X GET "https://connect.omnifact.ai/" \
  -H "X-API-Key: your_omnifact_api_key_here"
```

#### Response (`200 OK`)

```json theme={null}
{
  "status": "ok",
  "timestamp": "2026-08-03T12:00:00.000Z"
}
```

***

## List Supported File Types

`GET /v1/documents/supported-file-types`

Returns a list of all supported MIME types and file extensions for document ingestion.

#### Example Request

```bash theme={null}
curl -X GET "https://connect.omnifact.ai/v1/documents/supported-file-types" \
  -H "X-API-Key: your_omnifact_api_key_here"
```

#### Response (`200 OK`)

```json theme={null}
{
  "supportedMimeTypes": [
    "application/pdf",
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "text/plain",
    "text/csv",
    "text/markdown"
  ],
  "supportedExtensions": [".pdf", ".docx", ".txt", ".csv", ".md"]
}
```

***

## List Documents

`GET /v1/documents`

Retrieves documents in Space Uploaded Files. Filter by `spaceId` and paginate through results using `offset` and `limit`.

#### Query Parameters

| Parameter | Type      | Required | Description                                                      |
| :-------- | :-------- | :------- | :--------------------------------------------------------------- |
| `spaceId` | `string`  | Required | Filter documents belonging to a specific Space UUID.             |
| `offset`  | `integer` | Optional | Number of items to skip before returning results (default: `0`). |
| `limit`   | `integer` | Optional | Maximum number of items to return (default: `20`, max: `100`).   |

#### Example Request

```bash theme={null}
curl -X GET "https://connect.omnifact.ai/v1/documents?spaceId=spc_12345&offset=0&limit=10" \
  -H "X-API-Key: your_omnifact_api_key_here"
```

#### Response (`200 OK`)

```json theme={null}
{
  "total": 1,
  "limit": 10,
  "offset": 0,
  "items": [
    {
      "id": "doc_98765",
      "spaceId": "spc_12345",
      "name": "Employee_Handbook_2026.pdf",
      "status": "ready",
      "metadata": {
        "url": "https://example.com/handbook.pdf"
      }
    }
  ]
}
```

***

## Upload Document

`POST /v1/documents`

Uploads a new document file into a Space's Uploaded Files. The upload is processed asynchronously (content extracted, chunked, and vector-indexed).

#### Query Parameters

| Parameter | Type     | Required | Description        |
| :-------- | :------- | :------- | :----------------- |
| `spaceId` | `string` | Required | Target Space UUID. |

#### Request Body (`multipart/form-data`)

| Field      | Type     | Required | Description                                                                                 |
| :--------- | :------- | :------- | :------------------------------------------------------------------------------------------ |
| `file`     | `file`   | Required | The binary document file to upload.                                                         |
| `name`     | `string` | Optional | Overrides the original filename.                                                            |
| `metadata` | `object` | Optional | Optional JSON metadata object (a top-level `url` field is surfaced as a link on citations). |

#### Example Request

```bash theme={null}
curl -X POST "https://connect.omnifact.ai/v1/documents?spaceId=spc_12345" \
  -H "X-API-Key: your_omnifact_api_key_here" \
  -F "file=@/path/to/policy.pdf" \
  -F "name=Company_Policy_2026.pdf"
```

#### Response (`201 Created`)

```json theme={null}
{
  "id": "doc_98765",
  "spaceId": "spc_12345",
  "name": "Company_Policy_2026.pdf",
  "status": "processing"
}
```

***

## Get Document Details

`GET /v1/documents/{id}`

Fetches metadata and processing status for a specific document.

#### Path Parameters

| Parameter | Type     | Description        |
| :-------- | :------- | :----------------- |
| `id`      | `string` | The document UUID. |

#### Example Request

```bash theme={null}
curl -X GET "https://connect.omnifact.ai/v1/documents/doc_98765" \
  -H "X-API-Key: your_omnifact_api_key_here"
```

#### Response (`200 OK`)

```json theme={null}
{
  "id": "doc_98765",
  "spaceId": "spc_12345",
  "name": "Company_Policy_2026.pdf",
  "status": "ready",
  "metadata": {
    "url": "https://example.com/policy.pdf"
  }
}
```

***

## Update Document

`PATCH /v1/documents/{id}`

Updates a document's display name or metadata object.

#### Request Body (`application/json`)

| Field      | Type     | Required | Description                                                         |
| :--------- | :------- | :------- | :------------------------------------------------------------------ |
| `name`     | `string` | Optional | New display name for the document.                                  |
| `metadata` | `object` | Optional | Metadata object (replaces existing metadata; send `null` to clear). |

#### Example Request

```bash theme={null}
curl -X PATCH "https://connect.omnifact.ai/v1/documents/doc_98765" \
  -H "X-API-Key: your_omnifact_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated_Company_Policy_2026.pdf"
  }'
```

#### Response (`200 OK`)

```json theme={null}
{
  "id": "doc_98765",
  "spaceId": "spc_12345",
  "name": "Updated_Company_Policy_2026.pdf",
  "status": "ready"
}
```

***

## Delete Document

`DELETE /v1/documents/{id}`

Permanently removes a document and its indexed vectors from the Space Uploaded Files.

#### Example Request

```bash theme={null}
curl -X DELETE "https://connect.omnifact.ai/v1/documents/doc_98765" \
  -H "X-API-Key: your_omnifact_api_key_here"
```

#### Response (`204 No Content`)

## Next Steps

* Learn about [Published Spaces Chat API](/en/api-reference/published-space-chat)
* Read [Managing Uploaded Files](/en/platform/core-features/spaces/managing-uploaded-files) for admin instructions