> ## Documentation Index > Fetch the complete documentation index at: https://docs.conare.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`. > The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown. > Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1. > Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples. > Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt. # Upload a file > Stores a file as one searchable document, `:`. Its pages, slides, worksheet row ranges and sections are its parts: a search hit carries where it is in its metadata (`page`; `sheet` and `rows`; `slide`; `part`, `heading` and `lines`; `frame`; `image`), and a search answers a PDF's or image's page, a slide or a sheet's row range as a result of its own, its id `:$` (`page-3`, `slide-4`, ...), which `GET /namespaces/{namespace}/documents/{id}` reads alone; a text, Markdown or Word file is one result, the file. Uploading the same `id` again replaces it; the same bytes, name, metadata and options answer `result: unchanged`. - Body: the file's bytes, a multipart `file` part, or JSON `{"url": "https://..."}`, up to 512 MiB and 5,000 pages, sheets or slides. - Answers 200 once the parse ends within `wait` seconds, else 202: follow it with `GET /namespaces/{namespace}/files/{id}`. - The document's id is `:`; a file uploaded before 2026-10-25 keeps one document per part, `::`, until it is uploaded again. Every PDF page and image is read by OCR. ## OpenAPI ````yaml /openapi.yaml post /namespaces/{namespace}/files openapi: 3.1.0 info: title: Conare API version: '1' summary: Store your data, keep it in sync, and return the right context to your AI. description: > Write documents into namespaces, search them, and sync apps into them. - Base URL `https://api.conare.ai`; send `Authorization: Bearer sk-conare-…` (keys at conare.ai/dashboard/keys). - A multi-organization key sends `X-Conare-Org: ` on every request (`GET /organizations` lists them). - Bodies are JSON in snake_case; an unknown field is 400 `invalid_json` (`/v1` and `/v2` ignore it). Errors are `{"error": {"code", "message", "request_id"}}`. - Send every write with an `Idempotency-Key` and retry with the same key: a repeat within 24 hours replays the first answer. - 429 and 503 carry `Retry-After` (seconds). - `Conare-Degraded` marks a success that skipped or slowed part of search, e.g. `rerank` or `embed-busy`. contact: name: Conare url: https://conare.ai servers: - url: https://api.conare.ai security: - apiKey: [] tags: - name: Namespaces description: >- A namespace is a named set of documents, e.g. `docs` or `user-42`; the first write creates it. - name: Documents description: >- A document is `{ id, text, metadata }`, chunked and embedded on write; writing the same id replaces it. - name: Query description: >- Hybrid search (vector and keyword) over your namespaces, filtered by metadata and reranked. - name: Models description: >- Embed and rerank text with Conare's models, through Conare's own routes or OpenAI- and Cohere-compatible ones. - name: Sources description: Apps, buckets and custom sources, each kept in sync into one namespace. - name: Custom sources description: >- Documents you push from your own system, keyed by your `external_id`, with snapshot runs to mirror a whole set. - name: Parse description: Parse a file to Markdown without storing it. - name: Files description: >- Upload a file and Conare stores it as one document, each hit citing its page, slide, sheet rows or section. - name: Users description: >- Delete everything Conare holds of one of your users, across every namespace and source. - name: Events description: What changed, in order (`seq`), to read from a cursor. - name: Health description: Service health. - name: Organizations description: The organizations a key acts for. paths: /namespaces/{namespace}/files: parameters: - $ref: '#/components/parameters/Namespace' post: tags: - Files summary: Upload a file description: > Stores a file as one searchable document, `:`. Its pages, slides, worksheet row ranges and sections are its parts: a search hit carries where it is in its metadata (`page`; `sheet` and `rows`; `slide`; `part`, `heading` and `lines`; `frame`; `image`), and a search answers a PDF's or image's page, a slide or a sheet's row range as a result of its own, its id `:$` (`page-3`, `slide-4`, ...), which `GET /namespaces/{namespace}/documents/{id}` reads alone; a text, Markdown or Word file is one result, the file. Uploading the same `id` again replaces it; the same bytes, name, metadata and options answer `result: unchanged`. - Body: the file's bytes, a multipart `file` part, or JSON `{"url": "https://..."}`, up to 512 MiB and 5,000 pages, sheets or slides. - Answers 200 once the parse ends within `wait` seconds, else 202: follow it with `GET /namespaces/{namespace}/files/{id}`. - The document's id is `:`; a file uploaded before 2026-10-25 keeps one document per part, `::`, until it is uploaded again. Every PDF page and image is read by OCR. operationId: uploadFile parameters: - name: name in: query required: false description: The file's name, stored as `file` metadata (e.g. `Q3 report.pdf`). schema: type: string maxLength: 4096 - name: type in: query required: false description: >- The file's type, overriding `Content-Type` (`jpg`, `tif`, `xls`, `xlsm`, `heif` also accepted); unset, it is read from the bytes. schema: type: string enum: - pdf - xlsx - docx - pptx - doc - ppt - rtf - odt - ods - odp - csv - tsv - txt - md - png - jpeg - webp - tiff - gif - bmp - heic - name: id in: query description: >- The file's id (`file_id`), the end of its document's id; defaults to `name` with unsafe characters as `-`. schema: type: string - name: user in: query required: false description: The user of yours the file belongs to; its document carries `user`. schema: $ref: '#/components/schemas/User' - name: metadata in: query required: false description: A JSON object copied into the document's metadata. schema: type: string - $ref: '#/components/parameters/ParsePages' - $ref: '#/components/parameters/ParsePassword' - $ref: '#/components/parameters/ParseLayout' - $ref: '#/components/parameters/ParseWait' requestBody: required: true content: application/octet-stream: schema: type: string format: binary multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file; its filename is its name unless `name` is set. application/json: schema: type: object required: - url properties: url: type: string format: uri description: An https URL of the file, at a public address. application/pdf: schema: type: string format: binary text/csv: schema: type: string format: binary image/png: schema: type: string format: binary image/jpeg: schema: type: string format: binary responses: '200': description: >- Parsed within `wait`: `ready` with the document, `failed` with `error`, or `result: unchanged`. content: application/json: schema: $ref: '#/components/schemas/FileUpload' example: file_id: Q3-report.pdf name: Q3 report.pdf type: pdf state: ready source_id: src_4f1c2a9e0b7d4c3a8e6f1b2d uploaded_at: 1791460800000 pages: 2 ids: - src_4f1c2a9e0b7d4c3a8e6f1b2d:Q3-report.pdf ocr_failed: [] markdown: |- # Q3 report Revenue grew 12 percent. Outlook for Q4. parts: - locator: page: 1 markdown: |- # Q3 report Revenue grew 12 percent. ocr: true confidence: 0.97 - locator: page: 2 markdown: Outlook for Q4. ocr: false confidence: null without_text: pages: [] slides: [] images: [] '202': description: >- Still parsing after `wait`; `GET /namespaces/{namespace}/files/{id}` follows it. content: application/json: schema: $ref: '#/components/schemas/FileUpload' example: file_id: survey-scans.pdf name: survey-scans.pdf type: pdf state: parsing source_id: src_4f1c2a9e0b7d4c3a8e6f1b2d ids: [] pages: 0 without_text: pages: [] slides: [] images: [] '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '409': description: >- `file_replaced`: the file was deleted while the answer waited for its parse. content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: '`payload_too_large`: over 512 MiB, or over 20 MiB with `password`.' content: application/json: schema: $ref: '#/components/schemas/Error' '415': description: >- `unsupported_file`: not a type read here, or not the type declared; the message says which. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- `password_protected` (send `password`), `unreadable_file` (damaged) or `no_text`. content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' components: parameters: Namespace: name: namespace in: path required: true description: The namespace name. schema: $ref: '#/components/schemas/NamespaceName' ParsePages: name: pages in: query required: false description: >- Pages to read, e.g. `1-20,25` or `5-`: a PDF's pages, an image's frames or a deck's slides. schema: type: string examples: - 1-20,25 ParsePassword: name: password in: query required: false description: >- The password of a protected PDF or Office 2007+ file, on a file of at most 20 MiB; never stored. schema: type: string ParseLayout: name: layout in: query required: false description: '`true`: each part OCR read carries `blocks`, its page''s layout regions.' schema: type: boolean default: false ParseWait: name: wait in: query required: false description: >- Seconds, 0-300, to wait for the parse before answering 202 (`true` is 60, `false` 0); answers come within 105 s. schema: type: string default: '60' examples: - '60' - '0' - 'true' schemas: User: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$ description: >- A user id of yours, with at most 8 `:`; group users with `:` (`tenant-7:u_42`) and query a group by `user_prefix`. examples: - tenant-7:u_42 FileUpload: type: object description: >- An upload of `POST /namespaces/{namespace}/files` and its outcome; the fields of its file type. required: - file_id - type - state - ids - without_text properties: markdown: type: string description: 'Once `ready`: the whole document, as `ParseResult.markdown`.' parts: type: array description: 'Once `ready`: its parts, as `ParseResult.parts`.' items: $ref: '#/components/schemas/ParsePart' file_id: type: string name: type: string description: The file's name. uploaded_at: type: integer description: When the file was last uploaded or parsed, in Unix milliseconds. type: type: string enum: - pdf - xlsx - docx - pptx - csv - tsv - txt - md - image state: type: string enum: - queued - parsing - ocr - ready - failed description: >- `queued`, `parsing`: running. `ocr`: stored, some pages retried (`ocr_pending`). `ready`: stored. `failed`: see `error`. source_id: type: string description: >- The files source of the namespace (and user): the file's document is `:`. ocr_failed: type: array items: type: integer description: >- A PDF's or image's pages OCR could not read after its retries, 1-based. result: type: string const: unchanged description: >- The same bytes, name, metadata and options as the file's last parse; nothing was parsed again. error: type: object additionalProperties: true description: '`failed`: `code` and `message`.' ids: type: array items: type: string description: >- Once `ready`: the file's one document, `[:]` (a file uploaded before 2026-10-25 lists one per part until uploaded again). pages: type: integer description: A PDF's pages, or an image's pages (a TIFF's frames). pages_without_text: type: array items: type: integer deprecated: true description: >- Pages with no text, 1-based; not stored. Deprecated: `without_text.pages`. pages_ocr: type: integer deprecated: true description: 'Pages read by OCR. Deprecated: the `parts` with `ocr: true`.' images_ocr: type: integer deprecated: true description: 'Pictures read by OCR. Deprecated: the `parts` with `ocr: true`.' images_without_text: type: array description: >- A Word document's or deck's pictures OCR did not turn into text, with why; also in `without_text.images`. items: $ref: '#/components/schemas/PictureWithoutText' ocr_pending: type: array items: type: integer description: >- The pages, slides or pictures OCR is still reading, 1-based; each is stored with `ocr: true` when read. sheets: type: integer deprecated: true description: 'A workbook''s worksheets. Deprecated: `pages`.' slides: type: integer deprecated: true description: 'A deck''s slides. Deprecated: `pages`.' slides_without_text: type: array items: type: integer deprecated: true description: >- Slides with no text, 1-based; not stored. Deprecated: `without_text.slides`. without_text: type: object description: Everything the file stored no text for, in one place. required: - pages - slides - images properties: pages: type: array items: type: integer description: A PDF's or image's pages. slides: type: array items: type: integer description: A deck's slides. images: type: array items: $ref: '#/components/schemas/PictureWithoutText' description: A Word document's or deck's pictures. Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: > Stable, machine-readable, by status: - 400: `invalid_request`, `fetch_failed`, `invalid_json`, `invalid_namespace`, `invalid_id`, `invalid_metadata`, `invalid_filter`, `invalid_cursor`, `invalid`, `md5_mismatch`, `idempotency_key_required`, `invalid_path` - 401: `unauthorized`, `invalid_upload` - 402 (billed calls only): `credits_exhausted`, `spend_cap_reached`, `monthly_limit_reached`, `payment_failed` - 403: `forbidden`, `namespace_forbidden`, `key_scope_models_only`, `namespace_not_allowed` - 404: `namespace_not_found`, `document_not_found`, `source_not_found`, `model_not_found`, `key_not_found`, `file_not_found`, `parse_not_found`, `not_found` - 405: `method_not_allowed` - 409: `version_conflict`, `conflict`, `idempotency_in_progress`, `run_active`, `run_not_receiving`, `source_deleting`, `user_purging`, `upload_incomplete`, `namespace_has_sources`, `too_many_exclusions`, `push_source`, `pull_source`, `files_source`, `no_original`, `file_replaced`, `gcs_bucket_claimed`, `limit_reached` - 410: `upload_expired`, `model_retired` - 413: `payload_too_large`, `too_large` - 415: `unsupported_file`, `type_mismatch`, `unsupported_encoding` - 422: `idempotency_key_reused`, `no_text`, `unreadable_file`, `password_protected`, `gcs_access_denied`, `gcs_not_verified`, `gcs_bucket_not_found` - 429: `rate_limited` - 500: `internal_error`; 502: `upstream_error`; 501: `models_only` - 503: `unavailable`, `sources_unavailable`, `timeout`, `embed_unavailable`, `sync_storage_unavailable`, `sync_unconfigured`, `files_unconfigured`, `files_unavailable`, `gcs_unconfigured`, `gcs_unavailable`, `gcs_auth_failed` message: type: string request_id: type: string NamespaceName: type: string pattern: ^[a-z0-9][a-z0-9_-]{0,63}$ description: 1-64 characters of `a-z 0-9 _ -`, starting with a letter or digit. examples: - docs - user-42 ParsePart: type: object required: - locator - markdown - ocr - confidence properties: locator: type: object additionalProperties: true description: >- Where the part is, e.g. `{"page": 3}`, `{"slide": 4}`, `{"sheet": "Q3", "rows": "2-41"}` or `{"part": 2}`. markdown: type: string ocr: type: boolean description: Read by OCR from the page's image, not its text layer. confidence: type: - number - 'null' description: >- The mean probability (0-1) of the part's OCR tokens; null when OCR gave none. blocks: type: array description: With `layout=true`, the page's regions in reading order. items: type: object required: - type - bbox - order - content - conf properties: type: type: string description: >- The region's kind: `title`, `text`, `list`, `table`, `image`, `header`, `footer`, `footnote`, ... bbox: type: array items: type: number minItems: 4 maxItems: 4 description: >- `[x0, y0, x1, y1]` as shares of the page's width and height from its top left. order: type: integer description: Its place in the reading order. content: type: string description: Its text (a table as in `markdown`). conf: type: - number - 'null' description: The mean probability of its tokens; null when none was given. PictureWithoutText: type: object description: A picture in a Word or PowerPoint file that OCR did not turn into text. required: - image - reason properties: slide: type: integer description: 'A deck''s: the slide the picture is on.' image: type: integer description: >- The picture's number in reading order (per slide in a deck), as its part's `image` would be. heading: type: string description: 'A Word document''s: the headings the picture sits under.' width: type: integer description: 'With `too_small`: its width in pixels.' height: type: integer description: 'With `too_small`: its height in pixels.' reason: type: string enum: - too_small - not_raster - unreadable - not_read - no_text description: >- `too_small`: an icon or decoration. `not_raster`: a vector picture. `unreadable`: does not decode. `not_read`: over the file's picture limit, or OCR failed. `no_text`: none found. responses: Error: description: An error. `X-Request-Id` is also in the response headers. headers: X-Request-Id: schema: type: string Retry-After: description: Seconds to wait before retrying (429, 503). schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: text is required request_id: 7d0f4c1e-2b8a-4e39-9a61-3c5e8b2f9d04 securitySchemes: apiKey: type: http scheme: bearer bearerFormat: sk-conare-… description: >- A key from conare.ai/dashboard/keys with full access, some namespaces, or models only (`/embed`, `/rerank`, `/v1`, `/v2/rerank`, `/parse`). ```` ## Related topics - [Complete an upload](https://docs.conare.ai/pt-br/api-reference/custom-sources/complete-an-upload.md) - [Start an upload](https://docs.conare.ai/pt-br/api-reference/custom-sources/start-an-upload.md) - [Get an upload](https://docs.conare.ai/pt-br/api-reference/custom-sources/get-an-upload.md) - [Import an upload](https://docs.conare.ai/pt-br/api-reference/custom-sources/import-an-upload.md) - [Read a file](https://docs.conare.ai/pt-br/api-reference/files/read-a-file.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.