Upload a knowledge file
Extract and index one supported knowledge file in a workspace folder.
Endpoint
POST
/api/v1/workspaces/{workspace_id}/knowledge/filesAuthentication
| Operation class | Authentication | Minimum role | API key |
|---|---|---|---|
| dashboard-session-api | Dashboard session cookie; mutations also require X-CX-Request: 1. | admin | Not allowed |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
workspace_id | path | string | Yes | — |
Request body
multipart/form-data request schema
| Field path | Type | Reference | Format | Nullable | Required | Enum | Description |
|---|---|---|---|---|---|---|---|
$ | object | Body_uploadKnowledgeFile | — | No | Yes | — | — |
file | string | — | — | No | Yes | — | — |
folder_id | string or null | — | — | Yes | No | — | — |
name | string or null | — | — | Yes | No | — | — |
Example
curl --request POST 'https://operade.ai/api/v1/workspaces/ws_demo/knowledge/files' \ --cookie 'cx_session=YOUR_SESSION_COOKIE' \ --header 'X-CX-Request: 1' \ --form 'file=@./example-knowledge.txt'
{
"file": "./example-knowledge.txt"
}Responses
| Status | Description | Content |
|---|---|---|
4XX | Handled client error | application/json: ErrorResponse |
201 | Successful Response | application/json: KnowledgeDocument |
4XX application/json response schema
| Field path | Type | Reference | Format | Nullable | Required | Enum | Description |
|---|---|---|---|---|---|---|---|
$ | object | ErrorResponse | — | No | Yes | — | — |
error | object | ErrorItem | — | No | Yes | — | — |
error.code | string | — | — | No | Yes | — | — |
error.details | object | — | — | No | No | — | — |
error.message | string | — | — | No | Yes | — | — |
201 application/json response schema
| Field path | Type | Reference | Format | Nullable | Required | Enum | Description |
|---|---|---|---|---|---|---|---|
$ | object | KnowledgeDocument | — | No | Yes | — | — |
byte_size | integer | — | — | No | Yes | — | — |
chunk_count | integer | — | — | No | Yes | — | — |
created_at | string | — | date-time | No | Yes | — | — |
created_by | object | KnowledgeCreator | — | No | Yes | — | — |
created_by.email | string | — | — | No | Yes | — | — |
created_by.id | string | — | — | No | Yes | — | — |
created_by.name | string | — | — | No | Yes | — | — |
error | string or null | — | — | Yes | Yes | — | — |
folder_id | string or null | — | — | Yes | Yes | — | — |
id | string | — | — | No | Yes | — | — |
indexed_at | string or null | — | date-time | Yes | Yes | — | — |
name | string | — | — | No | Yes | — | — |
source_url | string or null | — | — | Yes | Yes | — | — |
status | string | — | — | No | Yes | "pending", "indexing", "ready", "failed" | — |
type | string | — | — | No | Yes | "text", "file", "url" | — |
updated_at | string | — | date-time | No | Yes | — | — |
Response example
{
"id": "string",
"name": "string",
"type": "text",
"status": "pending",
"error": "string",
"byte_size": 0,
"chunk_count": 0,
"created_by": {
"id": "string",
"name": "string",
"email": "string"
},
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z",
"indexed_at": "2026-01-01T00:00:00Z",
"source_url": "string",
"folder_id": "string"
}Errors
Reviewed common and route-declared errors are summarized here; the list is not exhaustive. Start with the distributed error index to find each code's canonical domain page.
| Status | Code | Description |
|---|---|---|
401 | unauthenticated | Authentication is missing, invalid, or revoked. |
403 | forbidden | The authenticated caller does not have access to this operation. |
404 | not_found | The requested workspace resource was not found. |
422 | validation_failed | The request did not pass field or business validation. |