> ## Documentation Index > Fetch the complete documentation index at: https://docs.evermind.ai/llms.txt > Use this file to discover all available pages before exploring further. # Upload a document > Upload a document for ingest. Ingest is asynchronous at the gateway: it answers 202 with status "queued" and a `task_id`, and the document id is minted downstream. Poll GET /api/v2/tasks/{task_id}, then resolve the id from GET .../documents. Ingest is only truly complete once that document reports `topic_count` greater than 0. - `content` is one content object: inline text, or a file already uploaded through POST /api/v2/object/sign and referenced by its object key as the content's `uri`. - `category_id` is optional — omit it to let the server classify the document into this base's taxonomy. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/knowledge_bases/{kb_id}/documents openapi: 3.1.0 info: title: EverOS Cloud Memory API version: 2.0.0 license: name: Apache-2.0 identifier: Apache-2.0 contact: name: EverMind AI email: service@evermind.ai url: https://github.com/EverMind-AI/everos-cloud-sdk-python description: >- Official Python client for the EverOS Cloud Memory API. Add, search, retrieve, and manage long-term memory for your AI applications over a typed interface (pydantic v2, with full type hints). Install and usage guides: https://github.com/EverMind-AI/everos-cloud-sdk-python servers: - url: https://api.evermind.ai description: Production security: - BearerAuth: [] paths: /api/v2/knowledge_bases/{kb_id}/documents: post: tags: - Knowledge summary: Upload a document description: >- Upload a document for ingest. Ingest is asynchronous at the gateway: it answers 202 with status "queued" and a `task_id`, and the document id is minted downstream. Poll GET /api/v2/tasks/{task_id}, then resolve the id from GET .../documents. Ingest is only truly complete once that document reports `topic_count` greater than 0. - `content` is one content object: inline text, or a file already uploaded through POST /api/v2/object/sign and referenced by its object key as the content's `uri`. - `category_id` is optional — omit it to let the server classify the document into this base's taxonomy. operationId: createDocument parameters: - name: kb_id in: path required: true schema: type: string title: Kb Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DocIngestBody' responses: '202': description: >- Accepted for asynchronous ingest. The body carries `status` and `task_id` only; `id` is absent (minted downstream) — resolve it from GET .../documents. content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope_DocIngestData_' '401': description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/GatewayError' '403': description: >- Authenticated but not permitted — either rejected by the auth service, or the account's memory API version does not match the interface version implied by the path (a v1 account calling an /api/v2 route). content: application/json: schema: $ref: '#/components/schemas/GatewayError' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit or quota exceeded. content: application/json: schema: $ref: '#/components/schemas/GatewayError' '503': description: >- The gateway could not reach the authentication service. Transient — retry with backoff. content: application/json: schema: $ref: '#/components/schemas/GatewayError' components: schemas: DocIngestBody: properties: title: type: string minLength: 1 title: Title description: >- Human-readable name for the document. Until the async ingest finishes this is the only handle the caller has — the document id is minted downstream, so GET .../documents is resolved by title. content: $ref: '#/components/schemas/ContentItem' description: The object to ingest (its uri = the SMM object_key) category_id: type: string title: Category Id description: Category id in this kb; omit for LLM auto-classify default: '' additionalProperties: false type: object required: - title - content title: DocIngestBody description: >- Public POST/PUT documents request body (design §3.2 / §3.3). ``content`` is the object to ingest (its ``uri`` = the SMM object_key). On PUT the ``doc_id`` rides the path, not the body; on POST no id is supplied — the engine mints it. SuccessEnvelope_DocIngestData_: properties: request_id: type: string title: Request Id description: Request trace id (peer to data) data: $ref: '#/components/schemas/DocIngestData' description: Endpoint-defined business result type: object required: - request_id - data title: SuccessEnvelope[DocIngestData] GatewayError: type: object additionalProperties: true description: >- Gateway error body. NOTE: shape is not yet uniform across auth/quota/ rate-limit paths — treat fields as best-effort. Commonly includes a `code`/`message` (flat) or an `error` object/string with a `message`. title: GatewayError HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail description: One entry per field that failed validation. type: object title: HTTPValidationError ContentItem: properties: type: type: string enum: - text - audio - image - doc - pdf - html - email title: Type description: >- What this item is: "text", "image", "audio", "doc", "pdf", "html" or "email". It selects how the content is parsed, so it must match the payload. text: anyOf: - type: string - type: 'null' title: Text description: Inline text, used when `type` is "text". source: anyOf: - type: string - type: 'null' title: Source description: >- Where the item came from — an origin label carried through to the memory. base64: anyOf: - type: string - type: 'null' title: Base64 description: >- The item's bytes inline, base64-encoded. NOTE: a non-text item that carries only `base64` is skipped by the parse step — the parser reads bytes from object storage — so use `uri` for anything that must actually be understood. uri: anyOf: - type: string - type: 'null' title: Uri description: >- Pointer to already-uploaded bytes: the object key returned by POST /api/v2/object/sign. This is the only form of a non-text item that gets parsed. ext: anyOf: - type: string - type: 'null' title: Ext description: >- File extension of the referenced content, e.g. "pdf" — used when the uri carries none. name: anyOf: - type: string - type: 'null' title: Name description: Original file name, kept for display and passed to the parser. source_info: anyOf: - additionalProperties: true type: object - type: 'null' title: Source Info description: >- Free-form provenance metadata stored alongside the item; a `size` here is passed to the parser. extras: anyOf: - additionalProperties: true type: object - type: 'null' title: Extras description: Free-form extra fields, passed through untouched. type: object required: - type title: ContentItem description: >- A single content element (appendix A). Current phase: only ``type="text"``. DocIngestData: properties: id: type: string title: Id description: >- Document id. Present only when the engine is called directly; the gateway's async ack omits it (the id is minted downstream), so SDK callers resolve it from GET .../documents by title. status: type: string title: Status description: Async task status (contract-nominal at the engine) default: queued task_id: type: string title: Task Id description: Async task handle (contract-nominal at the engine) default: '' type: object required: - status - task_id title: DocIngestData description: >- 202 response for document create / replace (design §3.2 / §3.3). ``id`` is the document id (engine-minted on create). The engine ingests synchronously; ``status`` / ``task_id`` mirror the async contract so this endpoint is wire-identical to the gateway edge — the real task lifecycle (queued -> processing -> success/failed) is maintained by msgbus/Redis, a separate layer. Ingest success is authoritative via GET documents/{id} (topic_count > 0). ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location description: Path to the offending field, from the body root. msg: type: string title: Message description: What is wrong with it. type: type: string title: Error Type description: Machine-readable validation-error kind. type: object required: - loc - msg - type title: ValidationError securitySchemes: BearerAuth: type: http scheme: bearer description: 'API key issued by EverOS, sent as `Authorization: Bearer `.' ````