Create upload session

Interface Description

Start a resumable upload and receive the session and operation identifiers, the maximum number of files per list request, and the recommended upload concurrency.

Endpoint

Field	Value
Method	`POST`
Path	`/openapi/v2/knowledge-bases/{knowledgeBaseId}/upload-sessions`
Operation ID	`createUploadSession`
Authentication	Bearer OpenAPI key

Parameters

Name	Location	Required	Type	Example	Description
`knowledgeBaseId`	path	Yes	string	knowledge-base-11111111-1111-4111-8111-111111111111	Knowledge-base identifier returned by knowledge-base APIs.
`Idempotency-Key`	header	Yes	string	mutation-2026-07-10-001	Client-generated key for safely retrying the same request. Reuse the same value for retries so duplicate work is not created.

Request Body

application/json

Field	Required	Type	Example	Description
`declaredFileCount`	Yes	integer	1	Total number of Markdown files declared for the upload session.
`declaredByteCount`	Yes	integer	37	Total number of Markdown file bytes declared for the upload session.

Request Example

bash

curl -X POST "https://openapi.example.com/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/upload-sessions" \
  -H "Authorization: Bearer <openapi-key>" \
  -H "Idempotency-Key: mutation-2026-07-10-001" \
  -H "Content-Type: application/json" \
  --data '{
  "declaredFileCount": 1,
  "declaredByteCount": 37
}'

Successful Responses

201

New upload session and its file-list and content-upload settings.

Field	Required	Type	Description
`session`	Yes	object	Upload session returned by the request.
`transport`	Yes	object	File-list request size and recommended upload concurrency for the new session.

Success Response Example

json

{
  "session": {
    "id": "upload-11111111-1111-4111-8111-111111111111",
    "operationId": "upload-operation-11111111-1111-4111-8111-111111111111",
    "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111",
    "state": "draft",
    "declaredFileCount": 1,
    "declaredByteCount": 37,
    "counts": {
      "selected": 0,
      "uploadRequired": 0,
      "skippedExisting": 0,
      "waitingReservation": 0,
      "rejectedDeleting": 0,
      "uploaded": 0,
      "finalized": 0
    },
    "errorCode": null,
    "expiresAt": "2026-06-18T00:00:00.000Z",
    "completedAt": null,
    "createdAt": "2026-06-17T00:00:00.000Z",
    "updatedAt": "2026-06-17T00:00:00.000Z",
    "actions": {
      "operation": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/upload-operation-11111111-1111-4111-8111-111111111111"
    }
  },
  "transport": {
    "manifestPageSize": 500,
    "contentUploadConcurrency": 8
  }
}

Error Codes

The table below lists every error response documented for this operation.

HTTP Status	Error Code	Explanation
401	`UNAUTHORIZED`	The Bearer API key is missing, malformed, unknown, revoked, or deleted.
404	`NOT_FOUND`	The requested resource was not found.
409	`CONFLICT`	The request conflicts with the resource's current state.
413	`PAYLOAD_TOO_LARGE`	The request body or requested file exceeds the size limit for this operation.
422	`VALIDATION_ERROR`	The request failed validation.
429	`RATE_LIMITED`	The request exceeded the configured rate limits.
500	`INTERNAL_ERROR`	The API encountered an internal error.
503	`DATABASE_REPOSITORY_UNAVAILABLE`	The data required by this operation is temporarily unavailable.

Create upload session ​

Interface Description ​

Endpoint ​

Parameters ​

Request Body ​

application/json ​

Request Example ​

Successful Responses ​

201 ​

Success Response Example ​

Error Codes ​

Next Steps ​