Create chunk

Append a chunk and embed it before returning. It inherits the document's tags and next chunkIndex. Search includes it when the chunk and document are enabled and the document has completed processing. Connector-synced chunks are read-only and return 403 with error.details.code: "CONNECTOR_MANAGED_RESOURCE_READ_ONLY"; change the source and re-sync, or exclude the document. Workspace API keys return 403; use a personal API key or scoped OAuth token.

OAuth scope: api:write.

POST/api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks

Authorization

X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Request examples use an API key. For OAuth, replace the X-API-Key header with Authorization: Bearer YOUR_ACCESS_TOKEN.

curl -X POST "https://www.sim.ai/api/v2/knowledge/string/documents/string/chunks" \  -H "X-API-Key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",    "content": "To reset your password, open Settings and choose Security."  }'
{
  "data": {
    "id": "4c1f9e77-2b3a-4f8d-9e10-6a2c8d4b1e05",
    "chunkIndex": 3,
    "content": "To reset your password, open Settings and choose Security.",
    "contentLength": 58,
    "tokenCount": 14,
    "enabled": true,
    "startOffset": 0,
    "endOffset": 0,
    "tag1": "string",
    "tag2": "string",
    "tag3": "string",
    "tag4": "string",
    "tag5": "string",
    "tag6": "string",
    "tag7": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}
{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}
{
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Request body must be sent as application/json"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}

Path parameters

documentId*string

Unique knowledge document identifier.

Length1 <= length
knowledgeBaseId*string

Unique knowledge base identifier.

Length1 <= length

Request body

application/json

Workspace scope and the text to embed.

TypeScript definitions

Use the request body type in TypeScript.

Response body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

POSTCreate knowledge basePOSTCreate knowledge connector