Dynamiq
Knowledge Bases

Upload documents to a knowledge base

Uploads one or more files for ingestion. Optional metadata is passed in the metadata form field as either a single JSON object (applied to every file) or a JSON array with one entry per file (its length must match the number of files). To replace existing items in place, pass their item IDs in the ids form field (JSON array, same length and order as files). The maximum request size is 128 MiB. Items are processed asynchronously; poll the items endpoints for status.

POST
/v1/knowledgebases/{knowledgebase_id}/upload

Authorization

personalAccessToken
AuthorizationBearer <token>

Personal Access Token of a Dynamiq user — the only credential accepted by the management API (api.*). Prefix dyn_pat_ (legacy uak_ tokens still authenticate). Send as Authorization: Bearer <token>.

In: header

Path Parameters

knowledgebase_id*string

Knowledge base UUID.

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/knowledgebases/497f6eca-6276-4993-bfeb-53cbbbba6f08/upload" \  -F files="[    \"string\"  ]"
{
  "data": [
    {
      "id": "8d9e0f1a-2b3c-4d4e-8f5a-6b7c8d9e0f1a",
      "name": "billing-faq.pdf",
      "status": "pending",
      "uploaded_at": "2026-06-10T09:00:00Z",
      "metadata": {
        "source": "billing-faq",
        "file_id": "8d9e0f1a-2b3c-4d4e-8f5a-6b7c8d9e0f1a",
        "dynamiq_item_id": "8d9e0f1a-2b3c-4d4e-8f5a-6b7c8d9e0f1a"
      }
    }
  ]
}
{
  "error": {
    "code": "bad_request",
    "message": "Bad Request",
    "details": {
      "input": "cannot be blank"
    }
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}
{
  "error": {
    "code": "not_found",
    "message": "Not Found"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null
  }
}

Upload documents (knowledge base hostname)

Uploads one or more files for ingestion, served on the knowledge base's own hostname (returned in the `hostname` field of the knowledge base resource) and authenticated with an access key. Optional metadata is passed in the `metadata` form field as either a single JSON object (applied to every file) or a JSON array with one entry per file (its length must match the number of files). To replace existing items in place, pass their item IDs in the `ids` form field (JSON array, same length and order as `files`). The maximum request size is 128 MiB. Items are processed asynchronously; poll the items endpoints for status.

Search knowledge base documents (management API)

Performs a semantic search over a knowledge base's documents using the knowledge base's configured embedder and retriever. This is the management-API equivalent of the hostname `POST /v1/documents/search`, addressed by knowledge base ID and authenticated with a personal access token.