openapi: "3.1.1" info: version: 1.0.0 title: POMA index4ai API # termsOfService: https://www.poma-ai.com/terms-of-service contact: name: POMA AI url: https://www.poma-ai.com email: support@poma-ai.com # license: # name: POMA AI description: | # Overview The POMA AI API enables you to transform unstructured documents and files into structured, machine-ready formats optimized for AI applications. The platform automatically processes uploaded files, breaking them down into semantic **chunks** and **chunk sets** that can be directly used for building RAG (Retrieval-Augmented Generation) applications, search systems, and other AI-driven workflows. ## Key Features - **Multi-format Support**: Process a wide variety of file types including documents (PDF, DOCX, PPTX), images (PNG, JPG, SVG), spreadsheets (XLSX, CSV), and more (see [Supported File Types](#supported-file-types)) - **Intelligent Chunking**: Automatically segments content into meaningful chunks and chunk sets for efficient processing - **Asynchronous Processing**: File ingestion creates background jobs that can be monitored and downloaded when complete - **Credit-based System**: Track usage and manage resources through a quota system - **RAG-Ready Output**: Generated POMA archives are optimized for integration with retrieval-augmented generation pipelines ## Billing on organisation projects Work on a project that belongs to an organisation — ingest and search — is charged to the organisation's **payer**, whoever performs it: a member's login token, account API key or project API key alike. The payer is the organisation's subscription when one is bound to it (for work of that subscription's product only). Work of an organisation without an active subscription (ingest, bucket ingest, search) is refused with `402` and `reason: orga_subscription_required`, carrying the organisation's `orga_id` (the `error` text stays `quota exceeded`, as for a credit shortfall): the owner does not pay for it, and an organisation needs its own subscription. An organisation whose subscription has ended answers `402 quota_exceeded`, as does a credit shortfall. Reading and deleting the documents of an organisation that no subscription pays for keeps working and consumes no credits; bucket ingest tasks already running pause (`pause_reason: orga_subscription_required`, or `credit_exhausted` for an ended subscription) and must be resubmitted once the organisation has a subscription. The payer's credits, subscriptions and index4ai storage cap are what the credit checks evaluate. The storage a payer holds is the free-pool stock plus the stock on its subscription row: an organisation's subscription holds the pages of the work charged to it, and the personal subscription row of an account holds that account's pages (a payer without a subscription row holds them in its free pool). So a `402` (`quota_exceeded`, `storage_cap_exceeded`) on an organisation project means the **payer's** balance or cap. Work on personal projects and on an account's default projects is charged to the caller, as before. Jobs stay owned by, and visible to, the account that created them. ## Ownership and access of organisation projects An organisation project belongs to the organisation: it is deleted with it (and restored with it), `account_id` is the organisation's owner (the account that pays) and the creating account is not exposed. The owner, the manager and the creator have no access to an organisation project's data through that role alone: only members of the organisation reach it, with a login token or account API key as with a project API key. Names are unique per organisation among live projects, and among an account's live personal projects. Only the organisation's manager (and internal staff) renames an organisation project. A project API key of an organisation project is checked against the organisation's membership at every use: when its holder is no longer a member the key answers `401`, with the same body as an expired key. Removing a member from the organisation also revokes that member's keys for the organisation's projects, so a member removed after this change and added again needs a new key. A key of a member removed before this change is not revoked: it answers `401` until the member is added again and then works again (no such key existed at release time). A key for an organisation project can be minted only for a member of the organisation (`403` otherwise). ## Organisation owners and managers Every organisation has one **owner** and one **manager**. One account can be both. The **owner** (`owner_account_id`, `caller_is_owner` on the `Orga` object) is the account that created the organisation and pays for its work: an enterprise account (or a POMA staff account, whose organisations get an internal subscription instead of buying one). The owner never changes through the API. The owner reads the organisation and its usage, deletes and restores it, buys and ends its subscription (Stripe checkout and customer portal, see `GET /orgaSubscriptions`), and names or replaces its manager by email (`PUT /orgas/{orgaId}/manager`). It can read the organisation's id, name, manager and timestamps, never its members or documents, and its projects only through the project listing it holds as manager (`GET /orgas/{orgaId}/projects`), unless it is a member itself. The **manager** (`manager_account_id` and `caller_is_manager`) holds authority over the organisation: renaming it, deleting and restoring it and its projects, and its members, invitations and roles. Neither role opens the organisation's documents. Data access comes from membership, and a manager can add any account to the organisation, itself included. The owner assigns a manager directly, without that account's consent and without any membership. The manager can hand the organisation back to its owner at any time (`POST /orgas/{orgaId}/manager/resign`). A manager is an account with role `enterprise`; the owner may always name itself. An unknown email, an account that cannot be a manager and an ambiguous email all answer `404` with `reason: manager_not_eligible`. Manager lookups are limited per owner (60 per hour, failed ones count). Every member, invitation and role write by a manager is recorded. When the manager is not the owner, the organisation's admins are also emailed (within about six minutes) and these writes are rate limited. A manager's own membership can be changed only by the manager. ## Integrator and management flags (retired) The former integrator and management account flags are retired. Every `enterprise` account can create and own organisations, be the manager of an organisation and buy organisation subscriptions; access follows the account role alone, and `PUT /accounts/{account_id}/kinds` no longer exists (it answers `404`). `is_integrator` and `is_management` are no longer part of `/me`, the account objects or the login response. Every account has its personal projects, default projects, quota and usage, and OAuth clients (MCP) get tokens for it like for any account. A checkout or plan switch request that carries `orga_id` is an organisation request and answers `409` with `reason: integrator_checkout_not_available` until organisation subscriptions are switched on for the deployment; it then addresses one organisation the account owns as an `enterprise` account. A request without `orga_id` is the personal checkout or switch, open to every account. Another spelling of that key in the body or the query (`orgaId`, `Orga_Id`, `orga-id`, any case of `orga_id`, `orgaid` or `orga-id` other than the exact `orga_id`) makes the checkout, switch, portal or invoice preview request a malformed organisation request, answered like a malformed `orga_id` (`404`), never a personal one. The customer portal, the invoice preview and the checkout's `sessionStatus` page are not behind that switch. ## Authentication The API uses Bearer token authentication. To get started: 1. **Register your email**: **POST `/registerEmail`**. 2. **Verify your email**: **POST `/verifyEmail`**. Complete registration with the verification code from email; the response includes a short-lived session token. 4. **Generate an API key (recommended for integrations)**: Call **POST `/generateApiKey`** with the session token in the `Authorization` header. The response includes an **opaque API key** you can use as the Bearer token for API access. Prefer this key over the session token for production and long-running clients. Generating a new API key will instantly revoke the prior one. All authenticated endpoints require a Bearer token (either the short-lived session token from verification, or the opaque API key from `/generateApiKey`) in the `Authorization` header. ## File Processing Workflow The typical workflow for processing files follows these steps: 1. **Ingest a file**: **POST `/ingest`** with the raw file as **octet-stream** (see that operation for details). The response includes a `job_id` that identifies the processing job. 2. **Monitor job status** — choose one: - **Streaming (SSE)**: GET `/status/v1/jobs/{job_id}` — Open a Server-Sent Events stream for live updates (see [Status service](#status-service-job-status-via-sse) below for docs and Swagger). - **Polling**: GET `/jobs/{job_id}/status` — Call this endpoint repeatedly to get the current status. Jobs progress through: - **pending** - The job is queued and waiting to start - **processing** - The job is actively being processed - **indexing** - index4ai jobs only: the document is converted and is now being indexed for search. Reported by both the SSE stream and the polled status endpoint - **done** - The job completed successfully and results are available. For an index4ai job this means the indexing succeeded too, not just the conversion - **failed** - The job encountered an error (error details are included in the response) - **blocked** - The job was rejected by policy (code 403) 3. **Get results**: Once a job reaches `done` status, retrieve the processed chunks and chunk sets. The recommended approach is GET `/jobs/{job_id}/result` which returns the data as structured JSON. **Alternatively**, GET `/jobs/{job_id}/download` returns the results as a downloadable POMA archive file. 4. **Delete a job** (optional): DELETE `/jobs/{job_id}` - Best-effort request to cancel and remove a job. The server accepts the request but does not guarantee immediate or complete deletion. ## Status service (job status via SSE) For streaming job status updates via Server-Sent Events instead of polling GET `/jobs/{job_id}/status`, use the Status API at `/status/v1/jobs/{job_id}`. - **Docs**: [https://api.poma-ai.com/status/v1/docs](https://api.poma-ai.com/status/v1/docs) - **Swagger**: [https://api.poma-ai.com/status/v1/swagger](https://api.poma-ai.com/status/v1/swagger) The stream applies the organisation membership rule of the job routes. A caller that is no longer a member of the organisation that owns the job's project gets `404` when it connects, the same as for an unknown job. Events are checked before they are sent, and an open stream checks the membership again about every 30 seconds, so a removal ends the stream within about 50 seconds, even before its first event, with a final `job_status` event (`status` `not_found`, `code` 404; `status` `unavailable`, `code` 503 when the check cannot be made). Jobs of personal projects are not affected, and privileged staff are not subject to the check. ## Output Format The downloaded POMA archive is a structured package containing: - **chunks.json** - Individual content segments extracted from the source file - **chunksets.json** - Grouped collections of related chunks - **assets/** - Associated files and resources referenced in the document These artifacts are designed to be directly consumable by RAG applications, vector databases, and other AI processing systems, enabling seamless integration of unstructured content into your machine learning pipelines. ## Account Management Manage your account and track usage: - **GET `/me`** - Retrieve your account information including account ID, username, email, subscription plan, and API key. - **POST `/generateApiKey`** — Rotate or create an account API key (authenticated). - **PUT `/updatePassword`**, **PUT `/updateAccount`** — Update password (JWT session only; not allowed with API-key auth) or username. - **GET `/myUsage`** - Get your account usage: index4ai pools (burst + subscription) ## Supported File Types The API supports a comprehensive range of file formats including: Documents: `pdf`, `doc`, `docx`, `dotx`, `rtf`, `txt`, `md`, `html`, `htm`, `xml`, `json`, `yaml`, `yml`, `.log`, `cir` Presentations: `ppt`, `pptx`, `pps`, `ppsx`, `pot`, `potx`, `key` Spreadsheets: `xls`, `xlsx`, `xlsb`, `xltx`, `csv`, `numbers`, `ods`, `odc` Images: `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tif`, `tiff`, `svg`, `webp`, `ico`, `heic`, `heif`, `psd` Archives & Specialized: `epub`, `mobi`, `djvu`, `dwg`, `dxf`, `dwf`, `dwfx`, `vsd`, `vsdx`, `ai`, `eps`, `ps`, `prn`, `xps`, `oxps`, `pub`, `mdi`, `pages`, `odp`, `odf`, `odt` Videos: `mp4`, `mov`, `webm`, `mkv`, `avi`, `m4v`, `mpeg`, `mpg` Audios: `mp3`, `wav`, `m4a`, `aac`, `ogg`, `flac`, `opus` servers: - description: POMA index4ai API version 1 url: https://api.index4.ai/v1 security: - BearerAuth: [] paths: /registerEmail: post: summary: Register new user description: | Registers a new user using their email address. **Request body** | Field | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------------------------------- | | `email` | string | Yes | The user's email address. Must be a valid and unique email. | | `username` | string | No | Optional username to associate with the account. | **Description** This endpoint creates a new user record based on the provided email address. The email field is required and must be unique within the system. If a username is provided it will be stored with the user profile. If omitted, the account will still be successfully registered using only the email. **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------------------------- | ------------------- | | `200` | Email registered successfully | application/json | | `400` | Bad request (e.g., invalid email or duplicate) | application/json | | `500` | Server error | application/json | operationId: registerEmail tags: - accounts security: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccountRegisterEmailRequest" responses: '200': description: Email registered successfully content: application/json: schema: type: string example: "Email registered successfully" '400': description: Bad request content: application/json: schema: type: string '500': description: Server error content: application/json: schema: type: string /registerOrgaUser: post: summary: Register a new user with an organisation's default invitation key description: | Same as `/registerEmail` (same email validation, same verification-code flow), authorised by the default invitation key of an organisation (`POST /orgas/{orgaId}/defaultInviteKey`). A new email creates an account with role `orga_user` (the rights of `demo`, ranked between `demo` and `customer`); an email that already has an account keeps its account: a `demo` account becomes `orga_user` when it joins, every other role stays. Nobody joins here and nothing is stored about the organisation. The user completes sign-up with `POST /verifyEmail`, sending the same `orga_id` and `invite_key` together with the code. That call, which proves the email, makes the account a `member` of the organisation (subject to the organisation's member limit; the key is checked again then, so a key that was regenerated in between no longer joins) and, for an account that is now a member, has never logged in, has no API key and is not staff, returns a new non-expiring account API key in `api_key` (one conditional write: an existing key is never replaced). Anyone else gets none. A verification without `orga_id` and `invite_key` (an ordinary login) never joins. Any problem with `orga_id` or `invite_key` (unknown or deleted organisation, no key generated, wrong or replaced key) answers `403` with reason `invalid_orga_invite`, so the response does not reveal which organisations exist. **Request body** | Field | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------- | | `orga_id` | string | Yes | The organisation's id. | | `invite_key` | string | Yes | The default invitation key, prefix `poma_orgainvite_`. | | `email` | string | Yes | The user's email address. Must be a valid email. | | `username` | string | No | Optional username to associate with the account. | operationId: registerOrgaUser tags: - accounts security: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccountRegisterOrgaUserRequest" responses: '200': description: Email registered successfully content: application/json: schema: type: string example: "Email registered successfully" '400': description: Bad request (missing field, invalid email or domain not allowed) content: application/json: schema: type: string '403': description: Invalid invitation (reason `invalid_orga_invite`). content: application/json: schema: type: object '429': description: Too many verification codes requested content: application/json: schema: type: string '500': description: Server error content: application/json: schema: type: string /orgaInviteInfo: post: summary: Read the name of the organisation an invitation key belongs to description: | Returns the name of the organisation whose current default invitation key (`POST /orgas/{orgaId}/defaultInviteKey`) is sent, so a sign-up page can say which organisation the invitation is for. The key is the only credential. Nothing else about the organisation is returned, nothing is stored and nobody joins. Any problem with `orga_id` or `invite_key` (unknown or deleted organisation, no key generated, wrong or replaced key) answers `403` with reason `invalid_orga_invite`, so the response does not reveal which organisations exist. The key travels in the body, never in the URL. operationId: getOrgaInviteInfo tags: - accounts security: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrgaInviteInfoRequest" responses: '200': description: The organisation's name content: application/json: schema: $ref: "#/components/schemas/OrgaInviteInfo" '400': description: Bad request (missing field) content: application/json: schema: type: string '403': description: Invalid invitation (reason `invalid_orga_invite`). content: application/json: schema: type: object '500': description: Failed to read the invitation content: application/json: schema: type: string /registerEnterprise: post: summary: Register new user requesting an enterprise account description: | Same as `/registerEmail` (same request, same verification-code flow, same responses), for a user who wants an enterprise account. The POMA team is alerted internally when a new account is created. The new account is created as a `demo` account and the team promotes it to `enterprise`. When the deployment sets `accounts.autoAllowEnterprise`, the account is created as `enterprise` directly. An email that already has an account is only sent a new code: its role is not changed and no alert is sent. The alert is best effort and never changes the response. **Request body** | Field | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------------------------------- | | `email` | string | Yes | The user's email address. Must be a valid and unique email. | | `username` | string | No | Optional username to associate with the account. | **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------------------------- | ------------------- | | `200` | Email registered successfully | application/json | | `400` | Bad request (e.g., invalid email or duplicate) | application/json | | `429` | Too many verification codes requested | application/json | | `500` | Server error | application/json | operationId: registerEnterprise tags: - accounts security: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccountRegisterEmailRequest" responses: '200': description: Email registered successfully content: application/json: schema: type: string example: "Email registered successfully" '400': description: Bad request content: application/json: schema: type: string '429': description: Too many verification codes requested content: application/json: schema: type: string '500': description: Server error content: application/json: schema: type: string # /requestAccessCode: # post: # summary: Request access code (alias for register) # description: | # Same handler and contract as **POST `/registerEmail`**. Exposed as an alternate path when self-registration is enabled. # operationId: requestAccessCode # tags: # - accounts # security: [] # requestBody: # required: true # content: # application/json: # schema: # $ref: "#/components/schemas/AccountRegisterEmailRequest" # responses: # 200: # description: Email registered successfully # content: # application/json: # schema: # type: string # example: "Email registered successfully" # 400: # description: Bad request # content: # application/json: # schema: # type: string # 500: # description: Server error # content: # application/json: # schema: # type: string /verifyEmail: post: summary: Verify email address description: | Verifies a user's email address using a one-time verification code. **Request body** | Field | Type | Required | Description | | ------- | ------ | -------- | ------------------------------------------------------------------------- | | `email` | string | Yes | The email address to verify. Must match an existing pending registration. | | `code` | string | Yes | The verification code sent to the user's email. | **Description** This endpoint validates the provided verification code for the specified email. If the code is correct and has not expired, the email is marked as verified. Upon successful verification, the server returns a JSON Web Token (JWT) that can be used for authenticated requests. A sign-up through `POST /registerOrgaUser` sends `orga_id` and `invite_key` in the body as well. Once the code is accepted the account joins the organisation as `member` when `invite_key` is the organisation's current default invitation key (a failed join does not fail the verification), and the response may carry `api_key` (see the response schema). Without those two fields the call never joins an organisation. **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------------------------------------------- | ------------------- | | `200` | Email verified successfully. Returns JWT token in response body. | application/json | | `400` | Bad request (e.g., invalid code, expired code, email mismatch) | application/json | | `500` | Server error | application/json | operationId: verifyEmail tags: - accounts security: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccountVerifyEmailRequest" responses: '200': description: Email verified successfully content: application/json: schema: $ref: "#/components/schemas/AccountRegisterEmailResponse" '400': description: Bad request content: application/json: schema: type: string '500': description: Server error content: application/json: schema: type: string /refresh: post: summary: Refresh access token description: | Exchange a valid refresh token for a new JWT access token and a rotated refresh token. **No authentication required** — the refresh token is the credential. The old refresh token is immediately revoked upon use. If a revoked refresh token is presented (token reuse), the entire token family is revoked as a security measure. The token is read from the request body, or — when the body omits it — from the `poma_refresh_token` httpOnly cookie set at login. Browser clients send the cookie and an empty body, so the body is optional. The rotated token inherits the `remember_me` lifetime of the session it replaces (7 days, or 30 with remember me). **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------------------------------------------------- | ---------------- | | `200` | New access token and rotated refresh token | application/json | | `401` | No refresh token presented, or it is invalid, expired or reused | application/json | | `429` | Too many refresh requests | application/json | | `500` | Server error | application/json | operationId: refreshToken tags: - accounts security: [] requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/RefreshTokenRequest" responses: '200': description: Token refreshed successfully content: application/json: schema: $ref: "#/components/schemas/RefreshResponse" '401': description: Unauthorized content: application/json: schema: type: string '429': description: Too many requests content: application/json: schema: type: string '500': description: Server error content: application/json: schema: type: string /logout: post: summary: Logout description: | Revokes refresh tokens for the authenticated account. If a `refresh_token` is provided in the request body, only that token's family is revoked. Otherwise all refresh tokens for the account are revoked (global logout). **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------- | ---------------- | | `200` | Logged out successfully | application/json | | `401` | Unauthorized | application/json | | `500` | Server error | application/json | operationId: logout tags: - accounts requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/LogoutRequest" responses: '200': description: Logged out successfully content: application/json: schema: type: object properties: message: type: string example: "logged out" '401': description: Unauthorized content: application/json: schema: type: string '500': description: Server error content: application/json: schema: type: string # /verifyAccessCode: # post: # summary: Verify access code (alias for verify email) # description: | # Same handler and contract as **POST `/verifyEmail`**. Exposed as an alternate path when self-registration is enabled. # operationId: verifyAccessCode # tags: # - accounts # security: [] # requestBody: # required: true # content: # application/json: # schema: # $ref: "#/components/schemas/AccountVerifyEmailRequest" # responses: # 200: # description: Email verified successfully # content: # application/json: # schema: # $ref: "#/components/schemas/AccountRegisterEmailResponse" # 400: # description: Bad request # content: # application/json: # schema: # type: string # 500: # description: Server error # content: # application/json: # schema: # type: string /me: get: summary: Retrieve account information description: | Retrieve the authenticated user's account information. **Description** This endpoint returns the account details for the currently authenticated user. The response includes all relevant metadata associated with the account, such as identification, contact information, subscription plan, and API credentials. *Response Object*: `MeResponse` (`PublicAccount` plus `can_create_orga`, `orga_subscriptions_enabled` and `enterprise_request_status`) | Field | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------------- | | `account_id` | string | Yes | Unique identifier for the account. | | `username` | string | Yes | The account's username. | | `email` | string | Yes | The email address associated with the account. | | `plan` | string | Yes | The subscription plan of the account (e.g., free, pro, enterprise). | | `api_key` | string | Yes | The account's API key for programmatic access. (long lived) | | `grill_subscription_type` | string | No | Active index4ai subscription plan identifier. Absent if no active subscription. | | `can_create_orga` | boolean | Yes | Whether the account may create or restore organisations: role `enterprise`, `member` or `dev`. | | `orga_subscriptions_enabled` | boolean | Yes | Whether organisation subscriptions are switched on for the deployment (`billing.orgaSubscriptions.enabled`); the same for every account. While `false` an organisation checkout or switch answers `409 integrator_checkout_not_available`. `true` does not promise a checkout: it can still answer `409 product_not_available` (primecut) or `409 release_gate_closed`. | | `enterprise_request_status` | string | No | `pending` while the account's request for an enterprise account (`POST /requestEnterprise`, `POST /registerEnterprise`) waits for staff. Absent when there is no open request, and for accounts that are already `enterprise` or higher. A mail tells the account when staff grant the request. | | `grill_subscription_ends_at` | string (date-time) | No | Present only while the active index4ai subscription is scheduled to end (cancelled, still active until this date). | **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------------------------------------------- | ------------------- | | `200` | Returns account information (PublicAccount). | application/json | | `401` | Unauthorized (e.g., invalid or expired token) | text/plain | | `404` | Account not found | text/plain | | `500` | Server error | text/plain | operationId: getMe tags: - accounts responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/MeResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: Account not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /myUsage: get: summary: Retrieve account usage description: | Retrieve product-split usage information for the authenticated user's account. **Description** Returns index4ai usage: - **index4ai**: four pools — `burst_ingest` and `burst_search` (base account-quota pools, non-resetting, always present) and `ingest_monthly` and `search_monthly` (subscription reset-windowed pools, present only when subscribed). For an index4ai subscription that keeps its one-time burst on the subscription (created while burst-on-subscription is enabled), `burst_ingest` is the base pool plus that subscription burst, while the subscription is active; it is consumed first, then the base pool, then `ingest_monthly`. Every other account sees the base pool alone, as before. **Response Object**: `AccountUsageResponse` | Field | Type | Required | Description | | ----------- | ------ | -------- | ---------------------------------------------- | | `grill` | object | Yes | index4ai usage: four pools (burst + subscription) | | `chart` | object | No | Daily usage series (MyUsageChart). Requested with `chart=true`, but BEST EFFORT — see the note under `chart` | **Responses** | Status Code | Description | Content Type | | ----------- | --------------------------------------------------- | ---------------- | | `200` | Returns usage information (AccountUsageResponse). | application/json | | `400` | Invalid `chart`, `chartResolution` or `chartProduct` value, or `chartResolution=billing_period` (not served on this API) | application/json | | `401` | Unauthorized (e.g., invalid or expired token) | text/plain | | `500` | Server error | text/plain | operationId: getAccountMyUsage tags: - accounts parameters: - name: chart in: query required: false description: | Opt in to the daily usage chart. Omit the parameter entirely for the previous response shape: with no `chart` key the body is byte-identical to what it was before the chart existed. Parsed with Go's `strconv.ParseBool`, so `true`/`1`/`t` enable it and `false`/`0`/`f` do not. A present-but-EMPTY value (`?chart`) is a 400, not "off". Anything else is a 400. **BEST EFFORT.** `chart=true` requests the chart, it does not guarantee it. If the chart cannot be built — a failing query, or the server's 2.5s chart budget exceeded — the response is still a `200` carrying the full `grill` data, with the `chart` key simply ABSENT. Treat a missing `chart` on a request that asked for one as "unavailable this time, retry", not as "this server does not support charts". The two are indistinguishable from the client side; that is the accepted price of not failing the credit balance with the chart. schema: type: boolean example: true - name: chartResolution in: query required: false description: | Selects how far back the chart goes, not how coarse it is: `week` returns 7 daily buckets, `month` returns 30. Granularity is reported in `chart.unit` and is always `day`. `billing_period` (the primeCut billing period, served under `/api`) is a `400` with `reason: chart_resolution_not_served`. Validated whenever the parameter is present, even when `chart` is absent or false. A present-but-empty value is a 400. schema: type: string enum: [week, month] default: week - name: chartProduct in: query required: false description: | Which usage the single series counts. One series per request — see the `chart` property of AccountUsageResponse for what each value includes. Validated whenever the parameter is present, even when `chart` is absent or false. A present-but-empty value is a 400. schema: type: string enum: [grill] default: grill responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/AccountUsageResponse" '400': description: | Invalid chart parameter. One of `Invalid chart flag`, `Invalid chart resolution` or `Invalid chart product`. No usage is queried. Also `chartResolution=billing_period`, which this API does not serve (`reason: chart_resolution_not_served`). A chart that FAILS to build is not in this class: that is a `200` with no `chart` key. See the `chart` query parameter. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /generateApiKey: post: summary: Generate account API key description: | Generates (or rotates) an opaque API key for the authenticated account. The account is identified from the Bearer token. The optional JSON body controls the key's lifetime: - **Empty body / omitted / `null` `expires_at`** — the key never expires. - **RFC3339 timestamp** — must be in the future and within the server's max lifetime cap (server default: 1 year). The stored value is used verbatim. The returned `api_key` is an opaque token that can be used as a Bearer token for all authenticated API endpoints. operationId: generateAccountApiKey tags: - accounts security: - bearerAuth: [] requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/GenerateAccountApiKeyRequest" responses: '200': description: API key generated successfully content: application/json: schema: $ref: "#/components/schemas/AccountApiKeyResponse" '400': description: | Invalid request: - malformed body (e.g. `expires_at` not RFC3339) - `expires_at` in the past or beyond the server's max lifetime cap content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /requestEnterprise: post: summary: Request an enterprise account description: | The authenticated account asks for an enterprise account. No request body. The request is stored (`enterprise_requests`, status `pending`). A repeat while one is pending changes nothing and does not alert again. While it is pending, `GET /me` returns `enterprise_request_status: pending`, and the account gets a mail when staff grant it. By default the POMA team is alerted internally with the account's email and a staff member grants it: the role is not changed by this call. When the deployment sets `accounts.autoAllowEnterprise`, the account's role is set to `enterprise` immediately, the request is recorded as granted by `auto`, and the team gets an informational alert. Alerts are best effort and never change the response. Accounts that are already `enterprise` or higher answer `409`. operationId: requestEnterprise tags: - accounts security: - bearerAuth: [] responses: '200': description: Request sent content: application/json: schema: type: string example: "Enterprise request sent" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: Account not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '409': description: | The account is already `enterprise` or higher. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /updateAccount: put: summary: Update account profile description: | Updates profile fields for the authenticated account. Currently requires **`username`** in the JSON body (same shape as account update models). operationId: updateOwnAccount tags: - accounts requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccountUpdateRequest" responses: '200': description: Account updated successfully content: application/json: schema: type: string '400': description: Bad request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /ingest: post: summary: Ingest a document into index4ai description: | Creates a **processing job** for the index4ai pipeline. Same request shapes as other raw file ingests: **`application/octet-stream`** body with **`Content-Disposition`**, or provide a **`X-Remote-URL`** header to fetch the file from a publicly accessible URL. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). Use the appropriate Bearer token for your integration. > > When using account-level credentials, supply the **`X-Project-ID`** header to identify the project. Protected projects reject account credentials — use a project API key instead. Error responses follow the `ErrorResponse` envelope: `{"error": "...", "code": , "reason": "..."}`. operationId: ingestFile tags: - index4ai parameters: - $ref: "#/components/parameters/XProjectID" - in: header name: Content-Disposition required: false schema: type: string default: 'attachment; filename="document.pdf"' description: Must include the original filename so the server can infer the format (e.g. `attachment; filename="document.pdf"`). Not required when using `X-Remote-URL`. - in: header name: X-Remote-URL required: false schema: type: string description: A publicly accessible URL to fetch the file from instead of uploading it in the request body. When provided, `Content-Disposition` and the request body are not required. example: "https://example.com/documents/report.pdf" - in: header name: X-Labels required: false deprecated: true schema: type: array items: type: string maxItems: 64 example: ["year:1982", "source:treasury", "some-label"] description: "Deprecated (D157): use X-Attributes (typed attributes); still accepted; removal will be announced.\n\nCategorical tags for query-time filtering. Stored HMAC'd (per-tenant secret) so values stay opaque in TurboPuffer. Equality-only matching; encode types as strings if needed (e.g. 'year:1982', 'source:treasury'). Normalized to stripped+lowercased before hashing — case-insensitive matching." - in: header name: X-Meta-Int-1 required: false deprecated: true schema: type: integer minimum: -9007199254740992 maximum: 9007199254740991 description: | Deprecated (D157): use X-Attributes (typed attributes); still accepted; removal will be announced. Customer-defined integer for range queries. Stored plaintext. Recommended convention: Unix epoch seconds (timestamp). Bounded to JS-safe int range. - in: header name: X-Meta-Int-2 required: false deprecated: true schema: type: integer minimum: -9007199254740992 maximum: 9007199254740991 description: | Deprecated (D157): use X-Attributes (typed attributes); still accepted; removal will be announced. Customer-defined integer for range queries. Stored plaintext. Recommended convention: revision/version number. Bounded to JS-safe int range. - in: header name: X-Unencrypted-Strings required: false schema: type: string example: '{"source":"jira","ticket":"PROJ-123"}' description: | Customer-defined plaintext string metadata for wildcard (glob) query-time filtering. JSON object of string keys to string values. Stored plaintext (unlike `X-Labels`/`X-Meta-Tags` which are HMAC'd), enabling case-insensitive Unix glob (`*`, `?`) matches via `unencrypted_strings_match` on search. Limits: max 32 keys; key 1..64 chars of `[A-Za-z0-9_]` (lowercased on ingest by index4ai); value ≤1024 chars; total payload ≤16384 chars. Returns 400 if any limit is exceeded. - in: header name: X-Attributes required: false schema: type: string example: '{"region":"emea","revision":12}' description: | Typed document attributes, superseding `X-Labels` / `X-Meta-Int-*` / `X-Unencrypted-Strings` (all of which stay live). `string`/`int`/`float`/`bool` and their arrays are inferred; `datetime` and `encrypted_text` must be declared via the `attribute_schema` form field, because neither is distinguishable from a plain string by value. A name's TYPE is fixed by the first write that uses it in the namespace and can never be changed; NAMES are permanent too and count against a budget of 64 per namespace. Attribute NAMES must match `^[a-z0-9_]{1,64}$` — lowercase only, matching index4ai's own rule; an uppercase name is a 400 here rather than a failed job later. **On index4ai ingest this header is the only carrier** (index4ai ingest is octet-stream; it has no multipart form path), so index4ai attributes are capped at 2048 chars per request. Declare `datetime` / `encrypted_text` types with the companion `X-Attribute-Schema` header. List the project's existing attributes with `GET /attributes` before declaring a new name; names are permanent. - in: header name: X-Attribute-Schema required: false schema: type: string example: '{"case_notes":{"type":"encrypted_text"}}' description: | Type declarations for entries in `X-Attributes`, shaped `{"name": {"type": "..."}}`. Required for `datetime` and `encrypted_text` — neither is distinguishable from a plain string by value. Same 2048-char cap as `X-Attributes`. A declaration that conflicts with the type already in force for that name returns 400 `attribute_type_conflict`. - in: header name: X-Canonical-URL required: false schema: type: string maxLength: 2048 example: "https://example.com/docs/report.pdf" description: | Citation URL associated with the ingested file. Forwarded to poma-core and surfaced in retrieval results so downstream consumers can cite the original document. - $ref: "#/components/parameters/XIncludeLinksSummary" - $ref: "#/components/parameters/XFooterOnly" requestBody: required: false content: application/json: schema: type: object description: >- Either job properties including file metadata when not sending raw bytes (legacy), or a **base64 upload** for clients whose tool-call plumbing can only send JSON (OpenWebUI uploads, most chat-app tool integrations): `{"file_base64": "...", "filename": "report.pdf"}`. Standard, URL-safe and unpadded base64 are accepted, and a `data:` URL prefix is tolerated. The decoded bytes are handled exactly like an octet-stream upload — same filename sanitising, same size limits — so every other option (labels, attributes, completion) still rides in the same headers a raw upload would send. The JSON body is subject to the server body limit (50 MB), so the decoded file is at most ~37 MB on this path; use octet-stream for larger files. properties: file_base64: type: string description: Base64 of the file bytes. filename: type: string description: Original filename, used for type detection and shown in job status. Required with file_base64. application/octet-stream: schema: type: string format: binary description: Raw file bytes. Not required when using `X-Remote-URL` header. responses: "201": description: Job created content: application/json: schema: $ref: "#/components/schemas/PublicJob" "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden (e.g. multipart not allowed) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "402": $ref: "#/components/responses/GrillPaymentRequired" "429": $ref: "#/components/responses/TooManyJobs" "500": description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /search: post: summary: Search (RAG context) description: | Runs **hybrid search** via the configured index4ai backend. Response shape depends on the request body’s **`format`** field: **`prompt_ready`** (the default) returns a rendered XML+Markdown block (**`RetrievalContext`**) whose `context` field carries `` wrappers, gap markers, sandwich ordering and token budgeting — ready to drop into an LLM prompt without further processing. **`json`** returns raw ranked hits (**`SearchResponse`**) instead. When index4ai names a `reason`, a **400** / **401** / **403** / **404** / **503** keeps its status, the reason is in the error body, and a 503 carries index4ai's `Retry-After`. Without a reason, errors are mapped to **400** / **401** / **403** / **404** when the error text matches, a 503 from index4ai or a connection failure to **503**, and other failures to **502**. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). > > When using account-level credentials, supply the **`X-Project-ID`** header. operationId: search tags: - index4ai parameters: - $ref: "#/components/parameters/XProjectID" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SearchRequest" responses: "200": description: OK content: application/json: schema: oneOf: - $ref: "#/components/schemas/RetrievalContext" - $ref: "#/components/schemas/SearchResponse" description: >- `RetrievalContext` when `format` is `prompt_ready` (the default), `SearchResponse` when `format` is `json`. "400": description: Bad request (validation or upstream index4ai 400) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized (missing/invalid token or upstream 401) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden (upstream index4ai 403) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Not found (upstream index4ai 404) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "402": $ref: "#/components/responses/GrillPaymentRequired" "502": description: >- Bad gateway (other index4ai / proxy errors). `reason: embedding_unavailable` means the embedding provider refused the call in a way that needs an operator (e.g. provider account or key); retrying will not help. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: >- Service unavailable: index4ai unreachable, or index4ai reported a transient failure. `reason: embedding_unavailable` means the embedding provider is rate limiting, failing or timing out. Retry after `Retry-After` seconds when the header is present. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (set when index4ai names a reason). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /searchInDoc: post: summary: Search within one document (RAG context) description: | Same as **POST /search**, but **`doc_filter`** is **required** (non-empty string). Same two response shapes, selected by **`format`**: **`RetrievalContext`** or **`SearchResponse`**. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). operationId: searchInDoc tags: - index4ai requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SearchInDocRequest" responses: "200": description: OK content: application/json: schema: oneOf: - $ref: "#/components/schemas/RetrievalContext" - $ref: "#/components/schemas/SearchResponse" description: >- `RetrievalContext` when `format` is `prompt_ready` (the default), `SearchResponse` when `format` is `json`. "400": description: Bad request (e.g. missing query or doc_filter) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden (upstream index4ai 403) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "502": description: >- Bad gateway (other index4ai / proxy errors). `reason: embedding_unavailable` means the embedding provider refused the call in a way that needs an operator (e.g. provider account or key); retrying will not help. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: >- Service unavailable: index4ai unreachable, or index4ai reported a transient failure. `reason: embedding_unavailable` means the embedding provider is rate limiting, failing or timing out. Retry after `Retry-After` seconds when the header is present. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (set when index4ai names a reason). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /attributes: get: summary: List attributes (index4ai namespace) description: | Lists every **typed attribute** the project's namespace has declared, with its POMA type. **Call this before declaring a new attribute on ingest** (`X-Attributes` / `X-Attribute-Schema`) and reuse a listed name and type where one fits. Attribute names are permanent once declared and count against `max_names`, so a near-duplicate (`year` vs `doc_year`) splits your filters across documents for good. An unreadable schema answers 503, never an empty list. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). operationId: listAttributes tags: - index4ai responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ListAttributesResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "410": description: The project's namespace was purged (`namespace_purged`). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: The attribute schema could not be read; retry. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /docs: get: summary: List documents (index4ai namespace) description: | Lists **document metadata** for the authenticated user’s project namespace in the index4ai backend. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). operationId: listDocs tags: - index4ai parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 500 default: 100 description: | Max documents to return. Omit this AND `cursor` to get today's "everything" behavior for namespaces up to 100 docs (legacy mode); larger namespaces return the first 100 with `has_more`/`next_cursor`. Values above 500 are clamped, not rejected; non-positive or malformed values fall back to the default (100) rather than erroring. - name: cursor in: query required: false schema: type: string description: Opaque pagination cursor from a previous response's `next_cursor`. Do not construct manually. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ListDocsResponse" "400": description: Bad request (e.g. malformed cursor) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden (upstream index4ai 403) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Not found (upstream index4ai 404) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "502": description: Bad gateway content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: Service unavailable (index4ai unreachable, connection refused) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "504": description: Gateway timeout (index4ai request timed out) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /docs/{docId}: get: summary: Get document metadata description: | Returns **metadata for one document** by path parameter **`docId`** (Fiber `:docId`). > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). operationId: getDocInfo tags: - index4ai parameters: - name: docId in: path required: true schema: type: string description: Document identifier (as used in index4ai / ingest). responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/DocInfo" "400": description: Bad request (e.g. empty docId) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden (upstream index4ai 403) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Document not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "502": description: Bad gateway content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: Service unavailable content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" patch: summary: Add, change or remove document attributes description: | Applies an **authoritative** patch to one document's typed attributes. This is the only channel that can **correct or remove** an attribute: ingest is *enrich-only* by design, so re-submitting a file never drops a value and a wrong one would otherwise be permanent. **Semantics** - A name **omitted** from `attributes` is left unchanged. - A name with a **value** is set or updated. - A name with a **`null` value is REMOVED**. Removing a value does **not** free the attribute **name** — names are permanent for the namespace and keep counting against the 64-name budget. Removing a name the namespace has never used is a `400`. `attribute_schema` declares types for attributes this document is the first in the namespace to use. It is **required** for `datetime` and `encrypted_text`, which are deliberately not inferred: by value they are indistinguishable from a plain string, and guessing either way is a silent correctness bug. Re-declaring a name that already has a type is what causes `attribute_type_conflict` — declare only genuinely new names. **Limits** (enforced upstream, over the resulting MERGED map rather than this request's slice): 64 attribute names per namespace, 40 KiB per document, 64 elements per array. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). > > When using account-level credentials, supply the **`X-Project-ID`** header. operationId: updateDocAttributes tags: - index4ai parameters: - name: docId in: path required: true schema: type: string description: Document identifier (as used in index4ai / ingest). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateDocAttributesRequest" responses: "200": description: >- Applied. `attributes` and `attribute_schema` are the document's full state AFTER the merge, so a client can apply them directly rather than refetching. Both are `null` — present, not absent — when the write applied but reading the document back failed; refetch in that case. `{}` means the document genuinely has no attributes left, which is exactly what removing the last one produces. content: application/json: schema: $ref: "#/components/schemas/UpdateDocAttributesResponse" "400": description: >- Invalid patch. `reason` carries the upstream discriminator: `attribute_type_conflict` (a declared type disagrees with the one in force), `attribute_budget_exceeded` (name budget or per-document size), or `attribute_invalid` (bad name, bad value, or a removal of a name the namespace never used). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden (upstream index4ai 403) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Document not found in this namespace content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "502": description: Bad gateway (other index4ai / proxy errors) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: >- Two different failures share this status. `reason: attribute_schema_busy` means the write lost every compare-and-set race on the namespace's attribute schema and **nothing was applied** — transient, retry the same body, and `Retry-After: 1` accompanies it. An index4ai that is UNREACHABLE also answers 503, but carries neither a `reason` nor `Retry-After`, so branch on `reason` being present rather than on the status alone. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" delete: summary: Delete a document description: | Deletes the document’s **vectors and storage** in the index4ai backend for the caller’s namespace. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). operationId: deleteDoc tags: - index4ai parameters: - name: docId in: path required: true schema: type: string description: Document identifier to delete. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/DeleteDocResponse" "400": description: Bad request (e.g. empty docId) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden (upstream index4ai 403) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "502": description: Bad gateway content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: Service unavailable content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /docs/{docId}/original: get: summary: Download the document's original file description: | Streams the **original uploaded file** of a document, decrypted, as an attachment (`Content-Type` from the stored type, `Content-Disposition`, `ETag` = the file's sha256, `Accept-Ranges: bytes`). One byte range is supported (`Range`, optionally `If-Range` with the ETag): `206` with `Content-Range`, or `416` when it starts past the end. For documents ingested from a URL/bucket/datalake only the source location is kept: the answer is then JSON `{doc_id, kind: "url", url}`. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). Free of charge. operationId: getDocOriginal tags: - index4ai parameters: - name: docId in: path required: true schema: type: string description: Document identifier (as used in index4ai / ingest). - name: Range in: header required: false schema: type: string description: "One byte range: `bytes=a-b`, `bytes=a-` or `bytes=-n`." - name: If-Range in: header required: false schema: type: string description: An earlier ETag; if it no longer matches, the whole file is sent. responses: "200": description: The whole file, or the kept source location as JSON. content: application/octet-stream: schema: type: string format: binary application/json: schema: type: object properties: doc_id: type: string kind: type: string enum: [url] url: type: string "206": description: The requested range (`Content-Range` set). content: application/octet-stream: schema: type: string format: binary "416": description: "Range not satisfiable (`Content-Range: bytes */`)." "400": description: Bad request (e.g. empty id) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: "Not found. `reason`: `not_found` (no such document), `files_not_attached` (no kept files: ingested before kept files existed), `original_unavailable`, `image_not_found`, `table_not_found`." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "410": description: "Project purged (`reason`: `namespace_purged`) — terminal." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "502": description: "Upstream failure, e.g. `reason` `files_integrity` (the stored file does not verify)." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: "Busy or unavailable (`reason` `files_busy`, `files_unavailable`, `files_too_large`); honour `Retry-After`." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "504": description: index4ai did not start answering in time content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /docs/{docId}/images: get: summary: List a document's images and tables description: | Which **images and tables** a document holds — ids, types and sizes, never content. Fetch each with `/docs/{docId}/images/{imageId}` or `/docs/{docId}/tables/{tableId}`; image ids are the ones search results reference. `coverage`: `ok` (complete), `capped`/`mismatch` (images kept, the list may miss some), `legacy_only` (only the pre-2026-09 copy exists), `none`. `complete` is true only for `ok`. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). Free of charge. operationId: listDocImages tags: - index4ai parameters: - name: docId in: path required: true schema: type: string description: Document identifier (as used in index4ai / ingest). responses: "200": description: The index. content: application/json: schema: type: object required: [doc_id, coverage, complete, images, tables] properties: doc_id: type: string coverage: type: string enum: [ok, capped, mismatch, legacy_only, none] complete: type: boolean images: type: array items: type: object properties: id: type: string mime: type: string length: type: integer source: type: string enum: [d147, legacy] tables: type: array items: type: object properties: id: type: string format: type: string enum: [html, markdown] length: type: integer source: type: string enum: [legacy] "400": description: Bad request (e.g. empty id) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: "Not found. `reason`: `not_found` (no such document), `files_not_attached` (no kept files: ingested before kept files existed), `original_unavailable`, `image_not_found`, `table_not_found`." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "410": description: "Project purged (`reason`: `namespace_purged`) — terminal." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "502": description: "Upstream failure, e.g. `reason` `files_integrity` (the stored file does not verify)." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: "Busy or unavailable (`reason` `files_busy`, `files_unavailable`, `files_too_large`); honour `Retry-After`." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "504": description: index4ai did not start answering in time content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /docs/{docId}/images/{imageId}: get: summary: Download one image of a document description: | One image's bytes, as an attachment (`Content-Security-Policy: sandbox`, `nosniff`; an SVG is never rendered as an active document). `ETag` is the image's sha256 when the image is kept with the document. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). Free of charge. operationId: getDocImage tags: - index4ai parameters: - name: docId in: path required: true schema: type: string description: Document identifier (as used in index4ai / ingest). - name: imageId in: path required: true schema: type: string description: An id from the images index (the id search results reference). responses: "200": description: The image. content: image/*: schema: type: string format: binary "400": description: Bad request (e.g. empty id) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: "Not found. `reason`: `not_found` (no such document), `files_not_attached` (no kept files: ingested before kept files existed), `original_unavailable`, `image_not_found`, `table_not_found`." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "410": description: "Project purged (`reason`: `namespace_purged`) — terminal." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "502": description: "Upstream failure, e.g. `reason` `files_integrity` (the stored file does not verify)." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: "Busy or unavailable (`reason` `files_busy`, `files_unavailable`, `files_too_large`); honour `Retry-After`." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "504": description: index4ai did not start answering in time content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /docs/{docId}/tables/{tableId}: get: summary: Download one table of a document description: | One table as stored — `text/html` or `text/markdown`, UTF-8 — as an attachment with a sandbox `Content-Security-Policy`. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). Free of charge. operationId: getDocTable tags: - index4ai parameters: - name: docId in: path required: true schema: type: string description: Document identifier (as used in index4ai / ingest). - name: tableId in: path required: true schema: type: string description: An id from the images index's `tables`. responses: "200": description: The table. content: text/html: schema: type: string text/markdown: schema: type: string "400": description: Bad request (e.g. empty id) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: "Not found. `reason`: `not_found` (no such document), `files_not_attached` (no kept files: ingested before kept files existed), `original_unavailable`, `image_not_found`, `table_not_found`." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "410": description: "Project purged (`reason`: `namespace_purged`) — terminal." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "502": description: "Upstream failure, e.g. `reason` `files_integrity` (the stored file does not verify)." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: "Busy or unavailable (`reason` `files_busy`, `files_unavailable`, `files_too_large`); honour `Retry-After`." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "504": description: index4ai did not start answering in time content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /docs/{docId}/pages/{page}: get: summary: Get one page of a document as an image description: | One page as a **WebP screenshot** (1-indexed), rendered on demand from the kept original (PDF, or an image, which is its own single page) or from the converted PDF of a non-PDF upload; never stored. `X-Page-Count` gives the document's page count. At most 1024 px on the long side (144 dpi). Served inline, `Content-Security-Policy: sandbox`, `nosniff`. > **Authentication**: Accepts a **login token**, **account API key**, or **project API key** (for a project with the `grill` product). Free of charge. operationId: getDocPage tags: - index4ai parameters: - name: docId in: path required: true schema: type: string description: Document identifier (as used in index4ai / ingest). - name: page in: path required: true schema: type: integer minimum: 1 description: Page number, from 1. responses: "200": description: The page. headers: X-Page-Count: description: The document's page count. schema: type: integer content: image/webp: schema: type: string format: binary "400": description: Page is not a number from 1 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: "`reason`: `not_found`, `files_not_attached`, `no_source`, `not_pdf_and_no_converted`, or `page_out_of_range` (the message gives the page count)." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "413": description: "`reason` `render_source_too_large` (download the original instead) or `render_too_large`." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": description: "`reason` `unsupported_source`: not a readable PDF or image." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: "Busy (`files_busy`); honour `Retry-After`." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "504": description: "`reason` `render_timeout`, or index4ai did not start answering in time." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /projects/info: get: summary: Get project by API key description: | Returns the project the presented **project API key** is bound to — the project id is embedded in the key, so no path or query parameter is needed. This endpoint accepts **only** a project API key (`poma_proj_*`). A missing key, an account login token, or an account API key are all rejected with `401`. operationId: getProjectInfo tags: - projects responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/Project" '401': description: Missing or non-project API key content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '403': description: Not allowed to access the bound project content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: Project not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" # Organisation endpoints /invitations/accept: get: summary: Accept organisation invitation description: | Accepts a pending organisation invitation using a one-time `token` from the invitation email. - If the caller is not authenticated, returns **401** with `{ "action": "authenticate", "message": "..." }` — the client should redirect to sign-in and retry with the token afterwards. - If the authenticated account's email does not match the invited email, returns **403** with `{ "error": "email_mismatch", "message": "..." }`. - If the token is expired, already used, or not found, returns **400** with `{ "error": "invitation_expired_or_not_found", "message": "..." }`. - On success, the caller is added to the organisation as a member and the invitation is marked `accepted`. operationId: acceptOrgaInvitation tags: - orgas parameters: - in: query name: token required: true schema: type: string description: One-time invitation token from the invitation email. responses: '200': description: Invitation accepted — caller has joined the organisation. content: application/json: schema: type: object properties: orga_id: type: string format: uuid message: type: string example: You have joined the organisation. '400': description: Token expired, already used, or not found. content: application/json: schema: type: object properties: error: type: string example: invitation_expired_or_not_found message: type: string '401': description: Caller not authenticated — must sign in before accepting. content: application/json: schema: type: object properties: action: type: string example: authenticate message: type: string '403': description: Authenticated account email does not match the invited email. content: application/json: schema: type: object properties: error: type: string example: email_mismatch message: type: string /orgas: get: summary: List my organisations description: | Returns every organisation the authenticated account is a member of (any role), manages or owns, one row per organisation. `caller_role` is absent for an organisation the caller manages or owns without a membership, and `caller_is_manager` and `caller_is_owner` say how the caller relates to it. An owner caller also gets `manager_email`. With `owned=true` only the organisations the caller owns are returned. Supports optional filtering and pagination via query parameters. operationId: listOrgas tags: - orgas parameters: - in: query name: name required: false schema: type: string description: Filter by organisation name (case-insensitive substring match). - in: query name: owned required: false schema: type: boolean description: When `true`, only the organisations the caller owns. The value is a boolean (`true`, `false`, `1`, `0`, `t`, `f`, `T`, `F`, `TRUE`, `FALSE`); anything else is a `400`. - in: query name: page required: false schema: type: integer default: 1 description: Page number (1-based). - in: query name: page_size required: false schema: type: integer default: 20 description: Number of results per page. responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/OrgaSearchResult" '401': description: Unauthorized content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string post: summary: Create organisation description: | Creates a new organisation. The authenticated account becomes its **owner** and pays for its work. Requires the **enterprise** account role or a POMA staff role (`member`, `dev`) (`GET /me` says: `can_create_orga`). A `demo` or `customer` account is refused with `403` (`orga_requires_customer`; the reason string predates this rule). Such an account can still join an organisation someone else created. The manager is the account named by `manager_email`. Without it the caller is the manager. An email that is unknown, belongs to an account that is not `enterprise` (a staff account included) and is not the caller itself, or matches more than one account when case is ignored, answers `404` with `reason: manager_not_eligible`. Manager lookups are limited per owner (default 60 per hour, every attempt counts): over the limit the answer is `429` with `reason: rate_limited`, `limit: manager_lookup` and a `Retry-After` header. An account that may not create an organisation learns nothing about the email and spends no lookup. A manager other than the owner is told by email. The organisation is created empty: no one gets a membership, neither the owner nor the manager. A manager (for an owner that does not name another manager, the owner itself) adds itself with `POST /orgas/{orgaId}/members` (role `admin` or `member`) when it needs data access. On a split orga the owner cannot reach data until the manager adds it or it names itself manager (`PUT /orgas/{orgaId}/manager`); it then receives only the owner-summary mail. Each owner is capped in the number of live organisations it owns: the tier default of its role, or the override staff set for the account (`limit_exceeded`, `resource: orga_owned`). A restore counts against the same cap. A membership is capped by `resource: orga_membership` and `orga_member` when it is added, not at create. Returns the created `Orga` object, with `owner_account_id`, `manager_account_id`, `caller_is_owner` and `manager_email`. The manager can subsequently invite other accounts via `POST /orgas/{orgaId}/invitations`. operationId: createOrga tags: - orgas requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateOrgaRequest" responses: '201': description: Organisation created. content: application/json: schema: $ref: "#/components/schemas/Orga" '400': description: | Missing `name` (text), a `name` that is not 1 to 200 characters after trimming or holds control or invisible formatting characters (`reason: invalid_request`). content: text/plain: schema: type: string application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '403': description: | Nothing was created. Either the account may not create an organisation (role `demo` or `customer`; `reason: orga_requires_customer`, an `ErrorResponse`), or its owned-organisation limit is reached (`reason: limit_exceeded`, a `LimitExceededError` with `resource` `orga_owned`; the membership caps bind when the owner adds itself, not at create). content: application/json: schema: anyOf: - $ref: "#/components/schemas/ErrorResponse" - $ref: "#/components/schemas/LimitExceededError" '404': description: | `reason: manager_not_eligible`: the `manager_email` is unknown, belongs to an account that is not `enterprise` (a staff account included) and is not the caller itself, or is ambiguous. Nothing was created. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '429': description: "Too many manager lookups (`reason: rate_limited`, `limit: manager_lookup`). `Retry-After` carries the wait in seconds." content: application/json: schema: $ref: "#/components/schemas/RateLimitedError" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '503': $ref: "#/components/responses/OrgaAccessUnavailable" /orgas/{orgaId}: get: summary: Get organisation description: | Returns the organisation identified by `orgaId`. The caller must be a member (any role), the organisation's manager or its owner. The response includes the caller's role in `caller_role` when the caller is a member, `caller_is_manager` and `caller_is_owner`, and `manager_email` for the owner. operationId: getOrga tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/Orga" '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Caller is not a member, the manager or the owner of this organisation. content: text/plain: schema: type: string '404': description: Organisation not found. content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string put: summary: Rename organisation description: | Updates the organisation name. Requires the organisation's **manager**. operationId: updateOrga tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateOrgaRequest" responses: '200': description: Organisation updated. Returns the updated `Orga` object. content: application/json: schema: $ref: "#/components/schemas/Orga" '400': description: "Missing `name` (text), or a `name` that is not 1 to 200 characters after trimming or holds control or invisible formatting characters (`reason: invalid_request`, an `ErrorResponse`)." content: text/plain: schema: type: string application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Caller is not the organisation's manager. content: text/plain: schema: type: string '404': description: Organisation not found. content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string '503': $ref: "#/components/responses/OrgaAccessUnavailable" delete: summary: Soft-delete organisation description: | Soft-deletes the organisation by setting `deleted_at`. Requires the organisation's **manager** or its **owner** (an owner needs this to offboard). The manager, the admins and the owner are told by email when the caller is not the manager or the manager is a controlled one. All active projects belonging to the organisation are cascade soft-deleted. Members are preserved. Deleting an organisation immediately frees the orga slot it occupied against each member's per-account organisation limit, even though the membership rows survive until the retention cleanup runs. This is the way out for a sole owner, who cannot leave their own organisation (see `DELETE /orgas/{orgaId}/members/{accountId}`). The organisation can be restored via `POST /orgas/{orgaId}/restore` within the retention period (`housekeeper.orgaPurgeAfter`, 30 days by default) — a cascade-deleted project is restored with it. Deleting the organisation also cancels all bucket ingest tasks of its projects, whatever their state, within one bucket-ingest admission pass (a few seconds); a cancelled task reads "Cancelled: the project's organisation was deleted." Work already handed to jobs completes and is charged. Restoring the organisation does NOT bring cancelled tasks back: members must resubmit them. After that window the housekeeper **permanently deletes** the organisation together with its project rows, its members and its invitations. This is irreversible. The purge waits until every project row still carrying the organisation's id has finished its own retention cleanup (index4ai namespace purged, storage pages released), so an organisation can outlive the window by a run or two. operationId: deleteOrga tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid responses: '200': description: Organisation deleted. content: application/json: schema: type: object properties: message: type: string example: ok '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Caller is not the organisation's manager or owner. content: text/plain: schema: type: string '404': description: Organisation not found. content: text/plain: schema: type: string '409': description: | The organisation still has an uncancelled subscription (`reason: orga_has_subscription`). Cancel it first. A subscription that is only scheduled to end, or has ended, does not block the delete. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: text/plain: schema: type: string '503': $ref: "#/components/responses/OrgaAccessUnavailable" /orgas/deleted: get: summary: List soft-deleted organisations description: | Returns all soft-deleted organisations the caller **manages or owns**. Includes `deleted_at` in the response. operationId: getDeletedOrgas tags: - orgas responses: '200': description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Orga" '401': description: Unauthorized content: text/plain: schema: type: string /orgas/{orgaId}/restore: post: summary: Restore a soft-deleted organisation description: | Restores a soft-deleted organisation by clearing `deleted_at`. Requires the organisation's **manager** or its **owner**. The owner never changes, so a restore cannot change who pays. The owner must still be allowed to create organisations (role `enterprise`, `member` or `dev`) and the manager must still be role `enterprise` or be the owner. Restoring an organisation counts against the owner's owned-organisation cap, like creating one: the owner must be under it. The manager, the admins and the owner are told by email when the caller is not the manager or the manager is a controlled one. Projects that were cascade soft-deleted with the organisation are also restored. Projects that were individually soft-deleted before the orga cascade remain deleted. Only possible until the housekeeper permanently deletes the organisation, which it does no earlier than `housekeeper.orgaPurgeAfter` after the delete (30 days by default) and possibly later, since it waits for the organisation's projects to finish their own retention cleanup. Treat the window as 30 days; once the purge has run this returns `404`. If the retention cleanup has already claimed any project that the delete cascaded (it is being purged or already purged, its index4ai namespace deleted), the restore is refused with `409` and `reason: orga_purge_in_progress`, and nothing is restored: the organisation stays deleted. operationId: restoreOrga tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid responses: '200': description: Organisation restored. Returns the restored `Orga` object. content: application/json: schema: $ref: "#/components/schemas/Orga" '400': description: Missing or invalid orgaId. content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '403': description: | Nothing was restored, for one of three reasons: * the caller is neither the organisation's **manager** nor its **owner** (only `error` and `code`); * the owner may not create an organisation: role `demo` or `customer` (`reason: orga_requires_customer`) — restoring is gated like creating an organisation; * the owner's owned-organisation cap is reached (`reason: limit_exceeded`, `resource: orga_owned`, with `limit` and `current`). content: application/json: schema: anyOf: - $ref: "#/components/schemas/ErrorResponse" - $ref: "#/components/schemas/LimitExceededError" '404': description: Organisation not found or not in deleted state. content: text/plain: schema: type: string '409': description: | `reason: manager_not_eligible` (the organisation's manager is not role `enterprise` and is not the owner: the owner names another manager with `PUT /orgas/{orgaId}/manager`, then restores; the same reason string as the lookup refusal, with status 409) or `reason: orga_has_no_owner` (the organisation has no owner; contact support) or `reason: orga_purge_in_progress` (a project of the organisation is being or has been purged; it cannot be restored). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '503': $ref: "#/components/responses/OrgaAccessUnavailable" /orgas/{orgaId}/projects: get: summary: List organisation projects description: | Returns the live projects of the given organisation as metadata only: `project_id`, `name`, `product`, `protected` and `created_at` (never `account_id`, the creator, `storage_base` or a key). Requires an **admin** (or the Release 1 `owner` membership) or being the organisation's manager, who needs no membership: this is how a manager finds the ids it renames, deletes and restores. The owner without a membership, a plain `member` and a stranger are refused with `403`. Internal staff have no bypass on this route. operationId: getOrgaProjects tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid responses: '200': description: OK content: application/json: schema: type: object properties: projects: type: array items: type: object properties: project_id: type: string description: Client-facing project identifier name: type: string product: type: string enum: [primecut, grill] protected: type: boolean created_at: type: string format: date-time '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Caller is neither an admin (or owner membership) nor the manager of this organisation. content: text/plain: schema: type: string '404': description: Organisation not found. content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string /orgas/{orgaId}/usage: get: summary: Get organisation usage description: | Returns the `GET /myUsage` body shape for an organisation, with the same query parameters. The caller must be a member of the organisation (any role), its manager or its owner, using a login token or account API key. The figures come from the **organisation's own subscriptions**, never from an account: - **index4ai:** while the organisation's index4ai subscription is active, `has_subscription` is true, `ingest_monthly` and `search_monthly` are its monthly pools, and `burst_ingest` is the burst pool on that subscription (zero when it has none). `burst_search` is always zero: an organisation has no free pool. - **Usage:** the index4ai `redundancy_rate` and the job part of the optional `chart` count the jobs charged to the organisation's subscriptions, including a subscription it ended and then bought again (both are added). Work charged before the organisation had a subscription is not counted. The index4ai search part of the chart counts the searches on the organisation's projects while it has an index4ai subscription. Without an index4ai subscription `has_subscription` is false and the pools are zero; an organisation whose index4ai subscription ended shows it the same way. operationId: getOrgaUsage tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid - name: chart in: query required: false description: Same as `GET /myUsage`. schema: type: boolean - name: chartResolution in: query required: false description: Same as `GET /myUsage`. schema: type: string enum: [week, month] default: week - name: chartProduct in: query required: false description: Same as `GET /myUsage`. schema: type: string enum: [grill] default: grill responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/AccountUsageResponse" '400': description: Invalid chart parameter, exactly as on `GET /myUsage`. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: text/plain: schema: type: string '403': description: | The caller is neither a member, the manager nor the owner of this organisation, or the organisation does not exist. A project API key is also refused with 403. content: text/plain: schema: type: string '409': description: | The organisation has no subscription of any product, ended ones included (`reason: orga_usage_requires_subscription`). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: text/plain: schema: type: string /orgas/{orgaId}/members: get: summary: List organisation members description: | Returns all members of the organisation. Requires **admin** role, or being the organisation's manager: a plain `member` is refused with `403`. Each member entry includes their `account_id`, `email`, `role`, and `created_at` (when they joined). operationId: getOrgaMembers tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/OrgaMembersListResponse" '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Caller is neither an admin nor the manager of this organisation. content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string post: summary: Add member to organisation description: | Adds an existing account to the organisation by **email address**. Requires **admin** role, or being the organisation's manager. - If the email does not match any existing account, returns **202** with a warning — the email is noted but no membership is created. - `owner` is **never** assigned here (`400 orga_role_retired`: the role is retired), whoever asks and whether or not the email has an account. - The manager may add any account, **itself included**; that membership gives data access. Every manager write is recorded, and for a controlled manager (not the owner) the organisation's admins are emailed and the writes are limited (default 120 per hour, `429 rate_limited` with `limit: manager_writes`). - An account that is already a member keeps its role when the same role is sent. Changing a member's role is not done here for an admin (`403`): an admin uses `PUT /orgas/{orgaId}/members/{accountId}/role`, which changes the role in one step. The manager may change a role here or there. Removing the member and adding it again with the other role is not an equivalent: the removal cancels the member's bucket tasks and cuts its reads until it is re-added. - Only the manager may change the manager's own membership (`403 manager_membership_protected` otherwise). - Only the owner account may remove or demote the owner account's own membership (`403 owner_membership_protected` otherwise). operationId: addOrgaMember tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AddOrgaMemberRequest" responses: '201': description: Member added successfully. content: application/json: schema: $ref: "#/components/schemas/OrgaMember" '202': description: Email not found — account does not exist yet. content: application/json: schema: type: object properties: warning: type: string example: "user@example.com was invited to orga ..., but email does not have account yet." '400': description: | Missing `email` or `role`, or `role` is `owner` (`reason: orga_role_retired`: the role is retired, use `admin`). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '403': description: | One of several causes, and nothing was changed in any of them: * the caller is neither an admin nor the manager; * the call changes the role of an existing member and the caller is not the manager; * the call changes the manager's own membership and the caller is not the manager (`reason: manager_membership_protected`); * the call lowers the role of the owner account's own membership and the caller is the manager (`reason: owner_membership_protected`); an admin caller is refused by the admin rule above and gets no `reason`; * the organisation is at its member limit (`resource: orga_member`, or `orga_membership` for the account that would join). That case carries `reason: limit_exceeded` with `resource`, `limit` and `current`; the other two carry only `error` and `code`. content: application/json: schema: anyOf: - $ref: "#/components/schemas/ErrorResponse" - $ref: "#/components/schemas/LimitExceededError" '429': description: | The caller is a controlled manager (it is not the organisation's owner) and is over its write limit (`reason: rate_limited`, `limit: manager_writes`; default 120 per hour, the owner's `manager_writes_per_hour` override applies when set). `Retry-After` carries the wait in seconds. Other callers are never limited here. content: application/json: schema: $ref: "#/components/schemas/RateLimitedError" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '503': $ref: "#/components/responses/OrgaAccessUnavailable" /orgas/{orgaId}/members/{accountId}: delete: summary: Remove member from organisation description: | Removes the account identified by `accountId` from the organisation. Requires **admin** role, or being the manager. Members may remove **themselves** without a role check. Only the organisation's **manager** may remove or change the manager's own membership (`403` with `reason: manager_membership_protected` for anyone else). An admin's way to cut a manager off is to remove the other accounts, ask the owner to name another manager, or delete the organisation. A controlled manager (not the owner) is limited in its member writes (`429 rate_limited`, `limit: manager_writes`). Only the organisation's **owner account** may remove its own membership: for anyone else the answer is `403` with `reason: owner_membership_protected`. Ownership is not transferable and is not a membership. operationId: removeOrgaMember tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid - in: path name: accountId required: true schema: type: string format: uuid description: Account ID of the member to remove. responses: '200': description: | Member removed. Also returned when the account was not a member of the organisation — removal is idempotent and reports no error for a no-op. content: application/json: schema: type: object properties: message: type: string example: ok '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '403': description: | The caller is neither an admin nor the manager, or the target is the manager and the caller is not (`reason: manager_membership_protected`), or the target is the owner account and the caller is not (`reason: owner_membership_protected`). Nothing was removed. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: | Organisation not found, or soft-deleted. An account that is simply not a member returns `200` — see above. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '429': description: | The caller is a controlled manager (it is not the organisation's owner) and is over its write limit (`reason: rate_limited`, `limit: manager_writes`; default 120 per hour, the owner's `manager_writes_per_hour` override applies when set). `Retry-After` carries the wait in seconds. Other callers are never limited here. content: application/json: schema: $ref: "#/components/schemas/RateLimitedError" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '503': $ref: "#/components/responses/OrgaAccessUnavailable" /orgas/{orgaId}/members/{accountId}/role: put: summary: Update member role description: | Updates the role of the account identified by `accountId` in one transaction, with no gap in membership: no bucket task of the member is cancelled and no read, job or project key of the member is refused at any point. Requires **admin** role, or being the organisation's manager. An admin can set `admin` or `member` for any member except the manager; it cannot grant `owner`, demote or remove the owner account's membership (`403 owner_membership_protected`) or change the manager's membership. - Only the manager may change the manager's own membership (`403 manager_membership_protected` otherwise). - Only the owner account may remove or demote the owner account's own membership (`403 owner_membership_protected` otherwise). - Sending the role a member already has changes nothing: no write, no event, no mail, no count. - A manager's change is recorded and, for a controlled manager (not the owner), mailed to the organisation's admins and counted against the manager write limit. An admin's change is neither recorded as a manager event, mailed nor limited, as for an admin's add and remove. The `owner` role is **retired**: `role: owner` is answered `400` with `reason: orga_role_retired`, for every caller and every member. The organisation's owner is its billing account (`owner_account_id`), not a role, and ownership is not transferable. Only the owner account may demote its own membership (`403 owner_membership_protected` for anyone else). operationId: updateOrgaMemberRole tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid - in: path name: accountId required: true schema: type: string format: uuid description: Account ID of the member to update. requestBody: required: true content: application/json: schema: type: object required: - role properties: role: type: string enum: - owner - admin - member description: New role for this member. responses: '200': description: | Member role updated. content: application/json: schema: $ref: "#/components/schemas/OrgaMember" '400': description: | `role` is `owner` (`reason: orga_role_retired`: the role is retired, use `admin`), or it is not a valid role. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: text/plain: schema: type: string '403': description: | Caller is neither an admin of the organisation nor its manager, or the member is the manager and the caller is not (`reason: manager_membership_protected`), or the member is the owner account, the new role is lower and the caller is not the owner (`reason: owner_membership_protected`). Nothing was changed. content: text/plain: schema: type: string '404': description: Organisation or member not found. content: text/plain: schema: type: string '429': description: | The caller is a controlled manager (it is not the organisation's owner) and is over its write limit (`reason: rate_limited`, `limit: manager_writes`; default 120 per hour, the owner's `manager_writes_per_hour` override applies when set). `Retry-After` carries the wait in seconds. Other callers are never limited here. content: application/json: schema: $ref: "#/components/schemas/RateLimitedError" '500': description: Server error content: text/plain: schema: type: string '503': $ref: "#/components/responses/OrgaAccessUnavailable" /orgas/{orgaId}/defaultInviteKey: get: summary: Whether the organisation has a default invitation key description: Manager only. Returns whether a key exists and when it was created, never the key. operationId: getOrgaDefaultInviteKey tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid responses: '200': description: Key status. content: application/json: schema: $ref: "#/components/schemas/OrgaDefaultInviteKeyStatus" '401': description: Unauthorized '403': description: Caller is not the manager of this organisation. '404': description: Organisation not found. '503': $ref: "#/components/responses/OrgaAccessUnavailable" post: summary: Generate the organisation's default invitation key description: | Manager only. Creates an opaque key with the prefix `poma_orgainvite_` and returns it in this response only; only a hash is stored. Generating again replaces the previous key, which stops working. People use the key with `POST /registerOrgaUser`. operationId: generateOrgaDefaultInviteKey tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid responses: '201': description: The new key. content: application/json: schema: $ref: "#/components/schemas/OrgaDefaultInviteKey" '401': description: Unauthorized '403': description: Caller is not the manager of this organisation. '404': description: Organisation not found. '429': description: A controlled manager reached its hourly write cap (reason `rate_limited`). '503': $ref: "#/components/responses/OrgaAccessUnavailable" delete: summary: Revoke the organisation's default invitation key description: | Manager only. Removes the key, so no key exists afterwards and the old one stops working (`GET` then reports `exists: false`). Idempotent: an organisation without a key also answers 204. Generate a new key with `POST`. operationId: revokeOrgaDefaultInviteKey tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid responses: '204': description: No key exists now. '401': description: Unauthorized '403': description: Caller is not the manager of this organisation. '404': description: Organisation not found. '429': description: A controlled manager reached its hourly write cap (reason `rate_limited`). '503': $ref: "#/components/responses/OrgaAccessUnavailable" /orgas/{orgaId}/invitations: post: summary: Invite account to organisation description: | Sends an invitation email to the given address. The recipient receives a link containing a one-time `token` that they can use with `GET /invitations/accept`. Requires **admin** role, or being the organisation's manager. - If a pending invitation for this email already exists, returns **409**. - Invitations expire after a server-configured TTL (typically 7 days). operationId: createOrgaInvitation tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - email properties: email: type: string format: email maxLength: 254 description: Email address to invite, at most 254 characters. responses: '201': description: Invitation created and email sent. content: application/json: schema: $ref: "#/components/schemas/OrgaInvitation" '400': description: Missing, invalid or over-long (more than 254 characters) `email`. content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Caller is neither an admin nor the manager of this organisation. content: text/plain: schema: type: string '409': description: A pending invitation for this email already exists. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: "A pending invitation already exists for this email." code: 409 reason: invitation_exists '429': description: | The caller is a controlled manager (it is not the organisation's owner) and is over its write limit (`reason: rate_limited`, `limit: manager_writes`; default 120 per hour, the owner's `manager_writes_per_hour` override applies when set). `Retry-After` carries the wait in seconds. Other callers are never limited here. content: application/json: schema: $ref: "#/components/schemas/RateLimitedError" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '503': $ref: "#/components/responses/OrgaAccessUnavailable" get: summary: List organisation invitations description: | Returns invitations for the organisation, filtered by `status`. Requires **admin** role, or being the organisation's manager. Supports pagination. `status` defaults to `pending`; use `all` to retrieve every invitation regardless of status. operationId: listOrgaInvitations tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid - in: query name: status required: false schema: type: string enum: [pending, accepted, cancelled, expired, all] default: pending description: Filter invitations by status. - in: query name: page required: false schema: type: integer default: 1 - in: query name: page_size required: false schema: type: integer default: 20 maximum: 100 responses: '200': description: OK content: application/json: schema: type: object properties: invitations: type: array items: $ref: "#/components/schemas/OrgaInvitation" meta: type: object properties: total: type: integer page: type: integer page_size: type: integer '400': description: Invalid `status` filter. content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Caller is neither an admin nor the manager of this organisation. content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string /orgas/{orgaId}/invitations/{invitationId}: delete: summary: Cancel invitation description: | Cancels a pending invitation. The one-time token is invalidated immediately and the invitation status is set to `cancelled`. Requires **admin** role, or being the organisation's manager. `invitationId` is the numeric `id` field from the `OrgaInvitation` object. operationId: cancelOrgaInvitation tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid - in: path name: invitationId required: true schema: type: integer format: int64 description: Numeric invitation ID. responses: '200': description: Invitation cancelled. content: application/json: schema: type: object properties: message: type: string example: cancelled '400': description: Invalid `invitationId` format. content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Caller is neither an admin nor the manager of this organisation. content: text/plain: schema: type: string '404': description: Invitation not found. content: text/plain: schema: type: string '429': description: | The caller is a controlled manager (it is not the organisation's owner) and is over its write limit (`reason: rate_limited`, `limit: manager_writes`; default 120 per hour, the owner's `manager_writes_per_hour` override applies when set). `Retry-After` carries the wait in seconds. Other callers are never limited here. content: application/json: schema: $ref: "#/components/schemas/RateLimitedError" '500': description: Server error content: text/plain: schema: type: string '503': $ref: "#/components/responses/OrgaAccessUnavailable" /orgas/{orgaId}/invitations/{invitationId}/resend: post: summary: Resend invitation email description: | Re-sends the invitation email for a pending invitation. Requires **admin** role, or being the organisation's manager. Each invitation can be resent at most **3 times**. Exceeding this limit returns **429**. To send more, cancel the existing invitation and create a new one. operationId: resendOrgaInvitation tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid - in: path name: invitationId required: true schema: type: integer format: int64 description: Numeric invitation ID. responses: '200': description: Email resent. Returns the updated invitation. content: application/json: schema: $ref: "#/components/schemas/OrgaInvitation" '400': description: Invalid `invitationId` format, or invitation is not in `pending` state. content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Caller is neither an admin nor the manager of this organisation. content: text/plain: schema: type: string '429': description: Resend limit (3) exceeded for this invitation. content: application/json: schema: type: object properties: error: type: string example: resend_limit_exceeded message: type: string '500': description: Server error content: text/plain: schema: type: string '503': $ref: "#/components/responses/OrgaAccessUnavailable" /orgas/{orgaId}/manager: put: summary: Set or change the manager of an organisation (owner) description: | The organisation's **owner** names its manager by email address. The named account must have role `enterprise`, or be the owner itself. It is assigned directly, without its consent, and needs no membership. The owner needs no membership either and gets no data access through this call. The payer does not change (the organisation's subscription), the organisation's subscriptions move to the new manager, and the new manager, the replaced manager and the organisation's admins are told by email. The new manager can resign (`POST /orgas/{orgaId}/manager/resign`). Works on live and soft-deleted organisations and needs no release gate. Naming the account that already is the manager answers `200` and changes nothing (no event, no mail), the lookup still counts. An owner can always name itself, whatever its role. Lookups are limited per owner (default 60 per hour, every attempt counts, a failed one too). Over the limit the answer is `429` with `reason: rate_limited`, `limit: manager_lookup`, a `Retry-After` header and `retry_after_seconds`. `404` without a `reason` when the organisation does not exist or is purged, or the caller has no relation to it. `403` without a `reason` when the caller is related (manager, admin, member) but is not the owner. `404` with `reason: manager_not_eligible` for an unknown email, an account that is not `enterprise` (a staff account included) and is not the caller itself, or an email that matches more than one account when case is ignored. The answer never says which. operationId: setOrgaManager tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid description: Organisation id. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SetOrgaManagerRequest" responses: '200': description: The organisation after the change (also when the named account already was the manager). Includes `manager_email` for the owner. content: application/json: schema: $ref: "#/components/schemas/Orga" '400': description: "Invalid `orgaId` or missing `email` (`reason: invalid_request`)." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '403': description: The caller is related to the organisation (manager, admin or member) but is not its owner. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: | The organisation does not exist or is purged, or the caller has no relation to it (no `reason`), or `reason: manager_not_eligible` (the email cannot be made manager: unknown, not an `enterprise` account other than the caller, or ambiguous). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '429': description: "Too many manager lookups (`reason: rate_limited`, `limit: manager_lookup`). `Retry-After` carries the wait in seconds." content: application/json: schema: $ref: "#/components/schemas/RateLimitedError" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /orgas/{orgaId}/manager/resign: post: summary: Resign as manager of an organisation description: | The organisation's current manager hands the organisation to its owner, which becomes its manager again. Placed subscriptions move to the owner. The resigning account keeps its membership if it has one, unless `leave` is `true`, in which case that membership is removed in the same transaction (an account that holds a membership cannot be erased until it leaves). The owner is told by email, and so are the organisation's admins. Works on live and soft-deleted organisations, so a manager can always leave. The organisation ends up managed by its owner: the owner can add itself as a member, which is mailed to the admins only when the writer is a controlled manager. The body is optional. `404` without a `reason` when the organisation does not exist or is purged, or the caller has no relation to it. `403` without a `reason` when the caller is related but is not the manager. `409` with `reason: manager_is_owner` when the manager already is the owner. operationId: resignOrgaManager tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid description: Organisation id. requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/ResignOrgaManagerRequest" responses: '200': description: The organisation after the change. The owner is its manager. content: application/json: schema: $ref: "#/components/schemas/Orga" '400': description: "Invalid `orgaId` or body (`reason: invalid_request`)." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '403': description: The caller is related to the organisation but is not its manager. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: The organisation does not exist or is purged, or the caller has no relation to it. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '409': description: "`reason: manager_is_owner`: the manager already is the owner." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /orgaSubscriptions: get: summary: List the subscriptions of your organisations description: | Lists the subscriptions bound to organisations: those of the organisations the caller **owns** (`role: holder`, the account that pays) and those of the organisations it **manages** (`role: manager`, which sees nothing about who paid). Every other caller gets `200 []`, also for an `orga_id` it has no relation to, so the answer never tells whether an organisation or a subscription exists. Newest first. A subscription is bound to one organisation when it is bought and never moves. `state` is `active`, `scheduled_to_end` (cancelled, still in force until `subscription_ends_at`) or `ended`. An organisation can be subscribed again only after the previous subscription has ended. Stripe ids are never returned. `synced_at` is when Stripe last confirmed the row. operationId: listOrgaSubscriptions tags: - orgas parameters: - in: query name: orga_id required: false schema: type: string format: uuid description: Only the subscriptions of this organisation. responses: '200': description: The subscriptions, possibly none. content: application/json: schema: type: array items: $ref: "#/components/schemas/OrgaSubscription" '400': description: "Malformed `orga_id` (`reason: invalid_request`)." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /orgas/{orgaId}/subscriptionRequests: post: summary: Ask the owner for a subscription (manager) description: | The organisation's **manager** asks its owner to buy or change a subscription for the organisation. The manager cannot buy, change or see the owner's subscriptions, and nothing else tells the owner that the organisation needs capacity. The request is recorded as the event `subscription_requested` and the owner and the organisation's admins are told by email. The body has a fixed vocabulary and **no free-text field**: the owner has no membership and must never receive free text. An unknown field is a `400`. One request per product within 24 hours: a second one answers `409` with `reason: request_recent`, `next_request_at` and a `Retry-After` header. Manager only. `403` for a caller related to the organisation that is not its manager, `404` without a reason for an unknown or purged organisation or an unrelated caller. operationId: requestOrgaSubscription tags: - orgas parameters: - in: path name: orgaId required: true schema: type: string format: uuid description: Organisation id. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrgaSubscriptionRequest" responses: '202': description: Recorded; the owner is told by email. content: application/json: schema: $ref: "#/components/schemas/OrgaSubscriptionRequestAccepted" '400': description: "Invalid `orgaId`, an unknown field, or a `product` or `intent` outside the allowed values (`reason: invalid_request`)." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '403': description: The caller is related to the organisation but is not its manager. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: The organisation does not exist or is purged, or the caller has no relation to it. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '409': description: "`reason: request_recent`: the same product was requested within 24 hours. `next_request_at` and `Retry-After` say when to try again." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /projects: post: summary: Create project description: | Creates a project for the authenticated account. The response includes a **one-time** `api_key` (member project API key) shown only at creation time. Required fields: **`product`** (`grill`), **`name`**. Optional: `orga_id` (creates an org-scoped project). The caller must be an `admin` member of a live organisation; the project is stored with the organisation's owner as `account_id` (an organisation without an owner keeps the creator) and the `api_key` returned is the caller's. A name already used by a live project of the organisation, or by a live personal project of the account, answers `400`. A deleted organisation answers `404`. The `protected` flag is set automatically: `false` for personal projects, `true` for org projects. Any value provided in the request body is ignored. operationId: createProject tags: - projects requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateProjectRequest" responses: '200': description: Project created content: application/json: schema: $ref: "#/components/schemas/CreateProjectResponse" '400': description: Invalid body, or a live project with this name already exists in the organisation (or among the account's personal projects) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '403': description: | Caller is not an admin of the specified orga. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: The organisation is deleted or does not exist. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '409': description: Project limit reached (personal or orga limit, depending on whether the project is created inside an orga); the message names the limit and the count, e.g. "Project limit reached (3/3)" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '503': $ref: "#/components/responses/OrgaAccessUnavailable" get: summary: List my projects description: | Returns the authenticated account's personal projects and the projects of the organisations it is a member of. An organisation's owner or manager without a membership sees none of its projects here (a manager lists them with `GET /orgas/{orgaId}/projects`). operationId: listProjects tags: - projects parameters: - name: orga_id in: query required: false description: | Only the projects of this organisation. An empty value is the same as omitting it. An organisation the caller is not a member of (or does not exist) lists nothing, so the response is `[]`. schema: type: string format: uuid responses: '200': description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Project" '400': description: "`orga_id` is not a uuid" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /projects/deleted: get: summary: List soft-deleted projects description: | Returns the soft-deleted projects visible to the authenticated account: its personal ones, and those of organisations it is a member of or manages (the manager may restore them). operationId: getDeletedProjects tags: - projects responses: '200': description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Project" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /projects/{projectId}: parameters: - in: path name: projectId required: true schema: type: string format: uuid description: Project UUID get: summary: Get project by ID operationId: getProject tags: - projects responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/Project" '400': description: Invalid project ID format content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: Project not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" delete: summary: Soft-delete project description: | Marks the project as deleted. Can be restored via **POST `/projects/{projectId}/restore`**. Default projects (`is_default: true`) cannot be deleted. Deleting the project also cancels all of its bucket ingest tasks, whatever their state, within one bucket-ingest admission pass (a few seconds); a cancelled task reads "Cancelled: the project was deleted." Work already handed to jobs completes and is charged. Restoring the project does NOT bring cancelled tasks back: members must resubmit them. operationId: deleteProject tags: - projects responses: '200': description: OK content: application/json: schema: type: boolean '400': description: | Invalid project ID format or attempt to delete a default project (`reason: cannot_delete_default_project`). For an organisation's default project only its manager, who may delete organisation projects, gets this answer; any other caller (an owner who is not the manager included) gets `403`. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '403': description: Not allowed to delete this project content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /projects/{projectId}/orga: patch: summary: Move a project into an organisation description: | Moves one of the caller's personal projects into an organisation. The move is one-way: a project already in an organisation cannot be moved again or taken out. Same rule as `POST /projects` with `orga_id`: - the caller created the project (a login token or account API key; a project API key is refused), and - the caller is `admin` or `owner` of the target organisation, which must not be deleted, and - the organisation has an owner and is below its project limit (set by its owner's role), and - an index4ai project needs the organisation's active index4ai subscription (an organisation without one pays for no index4ai work, so the moved project could not be used); a primecut project does not, and - the name is free among the organisation's live projects. After the move the project is organisation-owned: `account_id` becomes the organisation's owner and the caller is recorded as its creator. The project is `protected`, as organisation projects are created, so account credentials can no longer use it on product routes; its project API keys keep working. All work on it from then on is charged to the organisation's payer: index4ai work to the organisation's index4ai subscription, primecut work to its owner (see "Billing on organisation projects"). index4ai storage it already holds stays on the account that was charged for it. Default projects cannot be moved. The project's whole usage history moves with it: `GET /orgas/{orgaId}/usage` counts it from then on, including the work done (and paid for by the creator) before the move, and every member of the organisation can read that view. operationId: assignProjectOrga tags: - projects parameters: - in: path name: projectId required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: [orga_id] properties: orga_id: type: string format: uuid responses: '200': description: Moved. The updated project, with `orga_id` set and `protected` true. content: application/json: schema: $ref: "#/components/schemas/Project" '400': description: | Malformed `projectId`, or missing or malformed `orga_id` (plain text); a live project of the organisation already has the project's name (`Project already exists`); or a default project, which is JSON with `reason: cannot_modify_default_project`. content: text/plain: schema: type: string application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: text/plain: schema: type: string '403': description: | Not allowed: the caller did not create the project, is not `admin` or `owner` of the organisation, or the project is already in an organisation. A project API key is also refused with 403. content: text/plain: schema: type: string '404': description: Project not found, or the organisation is deleted. content: text/plain: schema: type: string '409': description: | Nothing was moved. One of: * the organisation is at its project limit (plain text naming the limit, e.g. "Orga project limit reached (5/5)"); * the organisation has no owner to bill (JSON, `reason: orga_has_no_owner`); * an index4ai project, and the organisation has no active index4ai subscription (JSON, `reason: orga_subscription_required`, with `orga_id` and `product`); * the project, the organisation or the caller's role in it changed while the move ran (plain text); retry. content: text/plain: schema: type: string application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: text/plain: schema: type: string '503': $ref: "#/components/responses/OrgaAccessUnavailable" /projects/{projectId}/usage: get: summary: Get project usage description: | Returns the `GET /myUsage` body for one project, with the same query parameters. Same access as `GET /projects/{projectId}`: the creator of a personal project, any member of an organisation project's organisation (any role), or a privileged account; login token or account API key. **Personal or default project:** the balances are the creator's account (the `grill` pools and `has_subscription`; a project has no pool of its own, so their `used` values include all of the creator's work), and the optional `chart` counts the jobs and index4ai searches run on this project, by anyone. If the creator is a demo account the response takes the `/myUsage` demo shape: no subscription pools and `credits_used` 0. **Organisation project:** the body of `GET /orgas/{orgaId}/usage` (the organisation's own subscriptions, never an account), with the index4ai `redundancy_rate` and the chart narrowed to the work on this project. A deleted project answers `404`. operationId: getProjectUsage tags: - projects parameters: - in: path name: projectId required: true schema: type: string format: uuid - name: chart in: query required: false description: Same as `GET /myUsage`. schema: type: boolean - name: chartResolution in: query required: false description: Same as `GET /myUsage`. schema: type: string enum: [week, month] default: week - name: chartProduct in: query required: false description: Same as `GET /myUsage`. schema: type: string enum: [grill] default: grill responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/AccountUsageResponse" '400': description: Malformed `projectId`, or an invalid chart parameter exactly as on `GET /myUsage`. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: text/plain: schema: type: string '403': description: | The caller may not read this project. A project API key is also refused with 403. content: text/plain: schema: type: string '404': description: Project not found. content: text/plain: schema: type: string '409': description: | The project belongs to an organisation that has no subscription of any product, ended ones included (`reason: orga_usage_requires_subscription`). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: text/plain: schema: type: string /projects/{projectId}/restore: parameters: - in: path name: projectId required: true schema: type: string format: uuid description: Project UUID post: summary: Restore a soft-deleted project description: | Clears `deleted_at` on a previously soft-deleted project. Fails with **409** if an active project with the same name already exists. **Retention cleanup lifecycle.** A deleted project moves `deleted` → `purging` → `purged` (see the `Project` schema's `purge_claimed_at` / `purged_at`). After the retention window (30 days by default) its index4ai data and storage pages are cleaned up: - `deleted`: restore succeeds with the data intact. - `purging`: cleanup is running; restore answers **409** with `reason: project_purging` — retry once it completes. - `purged`: index4ai lifts the namespace tombstone first (**502** `retrieval_unavailable` if it cannot, nothing changed), then restore succeeds and the project comes back **empty** (its documents and storage pages are gone); the response carries `data_purged: true`. operationId: restoreProject tags: - projects responses: '200': description: OK — the restored project content: application/json: schema: $ref: "#/components/schemas/RestoredProject" '400': description: Invalid project ID format content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Not allowed to restore this project content: text/plain: schema: type: string '404': description: Project not found or not deleted content: text/plain: schema: type: string '409': description: | An active project with the same name already exists (plain text), or retention cleanup is in progress (`reason: project_purging`, JSON error envelope). content: text/plain: schema: type: string application/json: schema: $ref: "#/components/schemas/ErrorResponse" '502': description: | The project was purged and index4ai could not lift its namespace tombstone (`reason: retrieval_unavailable`); nothing was changed — retry later. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: text/plain: schema: type: string /projects/{projectId}/protected: parameters: - in: path name: projectId required: true schema: type: string format: uuid description: Project UUID put: summary: Toggle project protection description: | Sets the `protected` flag on a project. When `true`, account-level credentials (login tokens, account API keys) are rejected on product routes — only project API keys are accepted. **Authorization**: Personal projects — caller must be the owner. Org projects — caller must hold at least `admin` role in the org. Default projects (`is_default: true`) cannot have their protection changed. operationId: updateProjectProtected tags: - projects requestBody: required: true content: application/json: schema: type: object required: - protected properties: protected: type: boolean responses: '200': description: OK — the updated project content: application/json: schema: $ref: "#/components/schemas/Project" '400': description: Invalid project ID format, missing `protected` field, or attempt to modify a default project content: application/json: schema: type: object properties: error: type: string code: type: string enum: - cannot_modify_default_project '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string code: type: string enum: - forbidden '404': description: Project not found content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string '503': $ref: "#/components/responses/OrgaAccessUnavailable" /projects/{projectId}/name: parameters: - in: path name: projectId required: true schema: type: string format: uuid description: Project UUID put: summary: Rename project description: | Changes a project's display name. The name is trimmed, must be non-empty, at most 64 characters, and unique among the organisation's live projects (organisation project) or among the account's live personal projects (personal project). The project id, API keys, and stored data are unaffected. **Authorization**: A personal project is renamed by its creator. An organisation project is renamed only by the organisation's manager (a member or not) and by internal staff; its creator and the organisation's admins cannot, and the owner of the organisation cannot unless it is also the manager. The manager is re-checked under the organisation's lock, so a manager changed during the request answers `403`. Project API keys are rejected (`403`). Default projects (`is_default: true`) cannot be renamed. operationId: renameProject tags: - projects requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string minLength: 1 maxLength: 64 responses: '200': description: OK — the updated project content: application/json: schema: $ref: "#/components/schemas/Project" '400': description: >- Invalid project ID format or request body; `name` empty, longer than 64 characters, or containing control/invisible characters; or the project is a default project (`reason: cannot_modify_default_project`) content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorResponse" - type: object properties: reason: type: string enum: - cannot_modify_default_project '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '403': description: Forbidden — personal project and the caller is not its creator; organisation project and the caller is not the organisation's manager (an admin or the creator included); or the caller presented a project API key content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorResponse" - type: object properties: reason: type: string enum: - forbidden '404': description: Project not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '409': description: >- `project_name_taken` — the organisation (or, for a personal project, the account) already has a live project with this name. `concurrent_modification` — the project moved to another org, or was deleted or changed, after the access check; retry. content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorResponse" - type: object properties: reason: type: string enum: - project_name_taken - concurrent_modification '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '503': $ref: "#/components/responses/OrgaAccessUnavailable" /projects/{projectId}/generateApiKey: parameters: - in: path name: projectId required: true schema: type: string format: uuid description: Project UUID post: summary: Generate project API key description: | Generates a new member project API key for the specified project. The key is returned once and cannot be retrieved again. An account's default project (`is_default: true`, no `orga_id`) does not support API key generation. An organisation's default project (`is_default: true` with an `orga_id`) does, like every organisation project. A key for an organisation project can be minted only for a member of the organisation, on every route including the admin route; a holder that is not a member is refused with `403`. A key of an organisation project is checked against membership at every use: when its holder stops being a member the key answers `401` with the same body as an expired key (removing the holder from the organisation revokes the key, so a holder who is added again needs a new key; a key of a holder removed before this change is not revoked and works again once the holder is added again). The optional `expires_at` body field controls the key's lifetime: - **Omitted or `null`** — the key never expires. - **RFC3339 timestamp** — must be in the future and within the server's max lifetime cap (server default: 1 year). The stored value is used verbatim. Typical UI presets (7d, 30d, 60d, 90d, custom) are computed client-side and submitted as an explicit `expires_at` timestamp. operationId: generateProjectApiKey tags: - projects requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/GenerateProjectApiKeyRequest" responses: '200': description: OK — the new API key (one-time) content: application/json: schema: type: string '400': description: | Invalid request: - invalid project ID format - attempt to generate API key for an account's default project (`code: cannot_modify_default_project`) - malformed body (e.g. `expires_at` not RFC3339) - `expires_at` in the past or beyond the server's max lifetime cap content: application/json: schema: type: object properties: error: type: string code: type: string enum: - cannot_modify_default_project '401': description: Unauthorized content: text/plain: schema: type: string '403': description: Not allowed, or the key's holder is not a member of the organisation the project belongs to. content: text/plain: schema: type: string '503': $ref: "#/components/responses/OrgaAccessUnavailable" '500': description: Server error content: text/plain: schema: type: string /apiKeys: get: summary: List the account's project API key metadata description: | Returns one page of metadata for the authenticated account's **active** project API keys (one entry per project that currently has a key), ordered by ascending key id. Revoked keys are excluded. Only **metadata** is returned — the raw key and its hash are never readable. Keys are SHA-256 hashed at rest, so a generated key value can only be seen once, at generation time. `expires_at: null` means the key never expires. Results are paginated. The response carries `next_cursor` (`null` on the last page); pass it back as the `after` query param to read the next page until `next_cursor` is null. operationId: listApiKeys tags: - accounts parameters: - name: limit in: query required: false description: Maximum number of entries to return. Clamped server-side to a maximum; 0 or omitted uses the server default. schema: type: integer minimum: 0 - name: after in: query required: false description: Opaque pagination cursor from a previous response's `next_cursor`. Returns entries after this position. schema: type: string responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/ApiKeyListResponse" '401': description: Unauthorized content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string /activeJobs: get: summary: List active jobs (pending and processing) description: | Returns structured `JobInfo` objects for jobs in **pending** and **processing** status for the authenticated account. Jobs are served from the in-memory cache with an mqueue fallback for pending jobs when the cache is cold. Privileged users (`dev`, `member` roles) may query any account via `?accountId=`. Organisation projects: jobs of an organisation project are listed only while the caller is a member of that organisation. After the caller was removed from the organisation those jobs no longer appear in this list. Privileged staff are not subject to this rule. If the membership check cannot be made the list answers `503`. operationId: getActiveJobs tags: - jobs parameters: - name: limit in: query required: false schema: type: integer default: 10 minimum: 1 maximum: 100 description: Max jobs returned per status (pending and processing each capped independently). Clamped to [1, 100]. - name: accountId in: query required: false schema: type: string description: Override account ID. Only honored for privileged users (`dev`, `member` roles). responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/ActiveJobsResponse" '401': description: Unauthorized content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string '503': description: Service temporarily unavailable. The check whether the caller may still read the job's organisation project could not be made. Retry later. content: text/plain: schema: type: string /failedJobs: get: summary: Search failed archived jobs description: | Query archived **failed** jobs: index4ai jobs only (`grill`, `grill-light`, `datalake-grill`, `datalake-grill-light`; a `jobTypes` filter is not applied). With a login token or account API key the listing is **account-wide**: every index4ai job the account ran, whatever project it ran in (including organisation projects the account has since left and deleted projects), the same scope as `GET /activeJobs`. `X-Project-ID` is ignored; narrow with `projectId`. A index4ai project API key lists its own project's jobs only, whatever `projectId` says. A primeCut project API key is refused with `403`. Query parameter names match the server (`jobId`, `accountId`, `projectId`, `startDate`, `endDate`, `page`, `pageSize`, `sortBy`, `descending`, `includeFailed`, `short`, `addUsage`, `addContactInfo`). Organisation projects: jobs of an organisation project are listed only while the caller is a member of that organisation. After the caller was removed from the organisation those jobs no longer appear in this list. Privileged staff are not subject to this rule. operationId: searchFailedArchivedJobs tags: - jobs parameters: - in: query name: jobId schema: type: string format: uuid - in: query name: accountId schema: type: string format: uuid - in: query name: projectId description: >- Project reference as stored on the job, matched exactly: `proj_` for a project, or `account_` for jobs attributed to no project (jobs archived before project attribution). A bare UUID matches nothing. schema: type: string - in: query name: startDate schema: type: string format: date-time - in: query name: endDate schema: type: string format: date-time - in: query name: page schema: type: integer default: 1 minimum: 1 maximum: 10000 description: >- 1-based page number. Clamped to [1, 10000]; out-of-range values are pinned to the nearest bound rather than rejected. - in: query name: pageSize schema: type: integer default: 100 minimum: 1 maximum: 500 description: >- Only honored for privileged users (`dev`, `member` roles) — every other caller gets 100 per page and this parameter is ignored. For privileged users: results per page, capped at 500; a value of 0 or below falls back to the default 100. - in: query name: sortBy schema: type: string - in: query name: descending schema: type: boolean - in: query name: includeFailed schema: type: boolean - in: query name: short schema: type: boolean - in: query name: addUsage schema: type: boolean - in: query name: addContactInfo schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/JobsSearchResult" '400': description: Bad request content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string /archivedJobs: get: summary: Search archived jobs description: | Query archived **done** jobs (and optionally merge failed — see `includeFailed=true`): index4ai jobs only (`grill`, `grill-light`, `datalake-grill`, `datalake-grill-light`; a `jobTypes` filter is not applied). With a login token or account API key the listing is **account-wide**: every index4ai job the account ran, whatever project it ran in (including organisation projects the account has since left and deleted projects), the same scope as `GET /activeJobs`. `X-Project-ID` is ignored; narrow with `projectId`. A index4ai project API key lists its own project's jobs only, whatever `projectId` says. A primeCut project API key is refused with `403`. Same query parameters as **GET `/failedJobs`**. Organisation projects: jobs of an organisation project are listed only while the caller is a member of that organisation. After the caller was removed from the organisation those jobs no longer appear in this list. Privileged staff are not subject to this rule. operationId: searchArchivedJobs tags: - jobs parameters: - in: query name: jobId schema: type: string format: uuid - in: query name: accountId schema: type: string format: uuid - in: query name: projectId description: >- Project reference as stored on the job, matched exactly: `proj_` for a project, or `account_` for jobs attributed to no project (jobs archived before project attribution). A bare UUID matches nothing. schema: type: string - in: query name: startDate schema: type: string format: date-time - in: query name: endDate schema: type: string format: date-time - in: query name: page schema: type: integer default: 1 minimum: 1 maximum: 10000 description: >- 1-based page number. Clamped to [1, 10000]; out-of-range values are pinned to the nearest bound rather than rejected. - in: query name: pageSize schema: type: integer default: 100 minimum: 1 maximum: 500 description: >- Only honored for privileged users (`dev`, `member` roles) — every other caller gets 100 per page and this parameter is ignored. For privileged users: results per page, capped at 500; a value of 0 or below falls back to the default 100. - in: query name: sortBy schema: type: string - in: query name: descending schema: type: boolean - in: query name: includeFailed schema: type: boolean - in: query name: short schema: type: boolean - in: query name: addUsage schema: type: boolean - in: query name: addContactInfo schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/JobsSearchResult" '400': description: Bad request content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string /jobs/{job_id}/status: get: summary: Retrieve the current job status description: | Retrieve the current status of a specific job. **Path Parameters** | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------ | | `job_id` | string | Yes | The unique identifier of the job to query. | **Description** This endpoint returns the current status of the specified job. Depending on the status, the response may include different types of information: - **pending** – The job is still in the queue and has not started processing. - **processing** – The job is currently being processed. - **done** – The job completed successfully. The response will include relevant output information, such as download URL. - **failed** – The job encountered an error and did not complete. Error details are included in the response. **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------------------------------------------- | ------------------- | | `200` | OK. Returns job status information (JobStatusResponse). | application/json | | `400` | Bad request (e.g., invalid job_id format) | text/plain | | `401` | Unauthorized (e.g., invalid or expired token) | text/plain | | `404` | Job not found | text/plain | | `500` | Server error | text/plain | Organisation projects: a job of an organisation project can be read only while the caller is still a member of that organisation. After the caller was removed from the organisation this route answers `404`, the same as for an unknown job. If the membership check cannot be made it answers `503` and reveals nothing about the job. Jobs of personal projects are not affected, and privileged staff are not subject to the check. operationId: getJobStatus tags: - jobs parameters: - in: path name: job_id required: true schema: type: string format: uuid description: Job ID responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" '400': description: Bad request content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '404': description: Job not found. Also the answer when the caller is no longer a member of the organisation that owns the job's project. content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string '503': description: Service temporarily unavailable. The check whether the caller may still read the job's organisation project could not be made. Retry later. content: text/plain: schema: type: string /jobs/{job_id}/results: get: summary: Get job results (JSON) description: | Return the same structured output as the *POMA archive* from **GET `/jobs/{job_id}/download`**, but as **JSON** instead of a binary download. The payload contains parsed **chunks** and **chunk sets**, plus `metadata`, and `images` / `tables` / `code` when the document produced any. If a member of the archive had to be left out, `skipped_members` says which and why. **Path Parameters** | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------------------------------- | | `job_id` | string | Yes | The unique identifier of the job whose results are being requested. | **Description** The server resolves the completed job’s result archive (local cache, persisted object storage, or the dedicated result service when configured) and returns the extracted JSON. This is convenient for clients that want to consume **chunks** / **chunksets** without handling a zip file. _Only jobs that have finished successfully with results available can return data. If the job is not **done** or output is missing, the request may fail with an error response._ **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------------------------------------------- | ------------------- | | `200` | OK. Parsed job results (see JobResults). | application/json | | `400` | Bad request (e.g., invalid `job_id` format) | text/plain | | `401` | Unauthorized (e.g., invalid or expired token) | text/plain | | `404` | Job not found (no such job for this caller) | text/plain | | `500` | Server error (e.g., job not ready, lookup failed, or failed to read or parse results) | text/plain | | `503` | Result service busy; retry after `Retry-After` seconds (see ResultBusy) | application/json | Organisation projects: a job of an organisation project can be read only while the caller is still a member of that organisation. After the caller was removed from the organisation this route answers `404`, the same as for an unknown job. If the membership check cannot be made it answers `503` and reveals nothing about the job. Jobs of personal projects are not affected, and privileged staff are not subject to the check. On this route a `503` can therefore also mean that the membership check could not be made (body `Service temporarily unavailable`, no `Retry-After`), not only that the result service is busy. operationId: getJobResults tags: - jobs parameters: - in: path name: job_id required: true schema: type: string format: uuid description: Job ID responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/JobResults" '400': description: Bad request content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '404': description: | Job not found: no such job for this caller, or its result archive has expired or been removed. A lookup that FAILED answers 500 instead. Also the answer when the caller is no longer a member of the organisation that owns the job's project. content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string '503': $ref: "#/components/responses/ResultBusy" /jobs/{job_id}/download: get: summary: Download *POMA archive* description: | Download the results of a completed job as a *POMA archive*. **Path Parameters** | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------------------------------- | | `job_id` | string | Yes | The unique identifier of the job whose results are being downloaded. | **Description** This endpoint provides a downloadable *POMA archive* containing all **chunks** and **chunk sets** generated by the job. These artifacts can be used to build or enhance your own *RAG* (Retrieval-Augmented Generation) applications or for other processing purposes. _Note: Only jobs with status `done` can be downloaded. Attempting to download a job that is `pending`, `processing`, or `failed` will return an error._ **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------------------------------------------- | ---------------------- | | `200` | Download job result file (POMA archive) | application/octet-stream | | `400` | Bad request (e.g., invalid job_id format, job not ready) | text/plain | | `401` | Unauthorized (e.g., invalid or expired token) | text/plain | | `404` | Job not found | text/plain | | `500` | Server error | text/plain | | `503` | Result service busy (`type=json` only); retry after `Retry-After` seconds | application/json | Organisation projects: a job of an organisation project can be read only while the caller is still a member of that organisation. After the caller was removed from the organisation this route answers `404`, the same as for an unknown job. If the membership check cannot be made it answers `503` and reveals nothing about the job. Jobs of personal projects are not affected, and privileged staff are not subject to the check. On this route a `503` can therefore also mean that the membership check could not be made (body `Service temporarily unavailable`, no `Retry-After`), not only that the result service is busy. operationId: downloadJobData tags: - jobs parameters: - in: path name: job_id required: true schema: type: string format: uuid description: Job ID - name: type in: query required: false schema: type: string enum: [archive, json] default: archive description: > Download format. `archive` (default) returns the `.poma.zip` result archive. `json` returns a JSON attachment (`Content-Disposition: attachment; filename="{jobId}.poma.json"`) with the structured results — equivalent to GET /jobs/{job_id}/results but as a downloadable file. The effective server default is operator-configured (`defaultDownloadType`); `archive` is the out-of-box value. - name: disallowRedirect in: query required: false schema: type: boolean default: false description: > When `true`, suppresses the signed-URL redirect and returns `{"url": ""}` as JSON instead. Only valid with `type=archive`. Combining `disallowRedirect=true` with `type=json` returns 400. responses: '200': description: Download job result file (poma archive or JSON attachment depending on `type`) content: application/octet-stream: schema: type: string format: binary application/json: schema: description: | Two different bodies share this content type, selected by the query parameters: `type=json` returns the parsed results, `type=archive` with `disallowRedirect=true` returns the signed archive URL instead of redirecting to it. anyOf: - $ref: "#/components/schemas/JobResults" - type: object description: Signed-URL body, returned only for `type=archive&disallowRedirect=true`. required: - url properties: url: type: string description: Signed URL for the POMA archive. example: "https://storage.poma-ai.com/results/550e8400.poma?signature=..." '400': description: Bad request content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '404': description: | Job not found: no such job for this caller, or its result archive has expired or been removed. A lookup that FAILED answers 500 instead. Also the answer when the caller is no longer a member of the organisation that owns the job's project. content: text/plain: schema: type: string '500': description: Server error content: text/plain: schema: type: string '503': $ref: "#/components/responses/ResultBusy" /jobs/{job_id}: parameters: - in: path name: job_id required: true schema: type: string format: uuid description: Job ID get: summary: Get job by ID description: | Returns **PublicJob** metadata for a job owned by the authenticated account. `404` means there is no such job for this caller. It is never returned for a lookup that failed — an unavailable datastore or message broker answers `500`, so clients may keep polling on `500` and stop on `404`. Organisation projects: a job of an organisation project can be read only while the caller is still a member of that organisation. After the caller was removed from the organisation this route answers `404`, the same as for an unknown job. If the membership check cannot be made it answers `503` and reveals nothing about the job. Jobs of personal projects are not affected, and privileged staff are not subject to the check. operationId: getJobById tags: - jobs responses: '200': description: OK content: application/json: schema: $ref: "#/components/schemas/PublicJob" '400': description: Bad request content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '404': description: | Job not found: no such job for this caller. Reserved for a lookup that completed and found nothing — a lookup that FAILED answers 500, so a 404 here means the job will not appear later. Also the answer when the caller is no longer a member of the organisation that owns the job's project. content: text/plain: schema: type: string '500': description: | Server error, including a job lookup that could not be completed (datastore or message broker unavailable). Transient: retry. content: text/plain: schema: type: string '503': description: Service temporarily unavailable. The check whether the caller may still read the job's organisation project could not be made. Retry later. content: text/plain: schema: type: string delete: summary: Delete a job description: | **Best-effort request** to delete a job. The server will attempt to cancel and remove the job but does not guarantee immediate or complete deletion. For example, a job that is already processing may complete before cancellation takes effect, or the job may remain visible for a short time. The API returns `204` once the delete intent has been accepted. **Late cancel (`409`)**: if processing finished before the cancel reached the processor, nothing is deleted and the job keeps its real outcome (`done` or `failed`). The response is `409` with `reason: "already_terminal"`. This is not a failure, and repeating the request while the job is still being finalised cannot change it — poll GET `/jobs/{job_id}/status`, then DELETE again once the job is terminal if the results should be removed (that call answers `204` and removes them). Cancelling is **idempotent**: a repeat DELETE of a job that was already cancelled answers `204`, not `409`. **Path Parameters** | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------- | | `job_id` | string | Yes | The unique identifier of the job to delete. | **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------------------------------------------- | -------------- | | `204` | Delete accepted (best-effort; job may still complete or appear) | — | | `400` | Bad request (e.g., invalid job_id format) | application/json | | `401` | Unauthorized (e.g., invalid or expired token) | application/json | | `404` | Job not found, or not this caller's job | application/json | | `409` | Job already finished processing; nothing was deleted. Retry only once the job is terminal. | application/json | | `500` | Server error | application/json | Organisation projects: a job of an organisation project can be read only while the caller is still a member of that organisation. After the caller was removed from the organisation this route answers `404`, the same as for an unknown job. If the membership check cannot be made it answers `503` and reveals nothing about the job. Jobs of personal projects are not affected, and privileged staff are not subject to the check. operationId: deleteJob tags: - jobs responses: '204': description: Delete accepted (best-effort); no response body '400': description: Bad request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '401': description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: | No such job for this caller (a job owned by another account answers 404 too, so the endpoint cannot be used to confirm it exists). Reserved for a lookup that completed and found nothing — a lookup that FAILED answers 500. Also the answer when the caller is no longer a member of the organisation that owns the job's project. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '409': description: | The job already reached a terminal state before the cancel arrived, so nothing was deleted and the job keeps its real outcome. `reason` is `already_terminal`. Not a failure: poll GET /jobs/{job_id}/status for the outcome, and DELETE again once the job is terminal to remove the results. A job that was already cancelled answers 204, not 409. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '503': description: Service temporarily unavailable. The check whether the caller may still read the job's organisation project could not be made. Retry later. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /jobs/{job_id}/retry: post: summary: Retry a job description: | Re-enqueues or retries processing. Requires a **privileged** JWT. The handler reads **`job_id` from the JSON body** (must match the job to retry; the path segment is the same identifier in normal clients). `stage` picks what is re-run: - `ingest` re-queues the whole job: poma-core converts the input again (billed again), then index4ai indexes it. Only for a job that failed during ingest; a job poma-core already converted (it has a job_archive row: any completed job, and an index4ai job from the moment poma-core finished) cannot be re-converted by a retry and answers **409**, `force` or not — re-submit the document instead. - `grill` re-runs only index4ai on the result poma-core already produced — no re-conversion, no second charge. Possible only while that result still exists (an index4ai job's result is removed about a day after creation) and index4ai's failure message is still on the stream; otherwise **409** with the reason. - omitted: `grill` when the job reached index4ai (it has a job_archive row), `ingest` when it failed during ingest. A job that reached index4ai is never re-converted: if its grill stage cannot run, the answer is **409** with the reason. The grill stage can be retried only after index4ai failed it; `force` applies to the `ingest` stage only. An index4ai failure because the document was too large for its pods is reported with status code 413, both on the job's status stream and in the job's status when polled. Organisation projects: a job of an organisation project can be read only while the caller is still a member of that organisation. After the caller was removed from the organisation this route answers `404`, the same as for an unknown job. If the membership check cannot be made it answers `503` and reveals nothing about the job. Jobs of personal projects are not affected, and privileged staff are not subject to the check. Who pays: an `ingest` retry is charged to the project's payer, exactly as the original job was, never to the account that submitted the job. For an organisation project that is the holder of the subscription bound to the organisation, also when the submitter has left the organisation. A personal project is charged to its account. The payer is resolved and checked before anything is changed (a retry runs no credit check): if the project's organisation has no owner, has no subscription that pays for the work, its subscription is for another product, or the caller's access to the project's organisation cannot be checked, the job stays failed and the route answers `409`, `402` or `503` (below). operationId: retryJob tags: - jobs parameters: - in: path name: job_id required: true schema: type: string format: uuid description: Job ID (should match body `job_id`) - in: query name: stage required: false schema: type: string enum: [grill, ingest] description: Stage to re-run. Omit to choose from where the job failed (see above). - in: query name: force required: false schema: type: boolean default: false description: Retry a job that did not fail (stage `ingest` only). Does not extend to a job poma-core already converted, which answers 409 regardless. Honoured for privileged callers only. requestBody: required: true content: application/json: schema: type: object required: - job_id properties: job_id: type: string format: uuid description: Job ID to retry responses: '200': description: Retry accepted content: application/json: schema: type: string example: "Job retried successfully" '400': description: Bad request content: text/plain: schema: type: string '401': description: Unauthorized content: text/plain: schema: type: string '402': description: | The project's organisation subscription is for another product than the job, or has ended (`reason: quota_exceeded`); or the project's organisation never had an index4ai subscription (`reason: orga_subscription_required`, with `orga_id`). The job stays failed. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" '404': description: Job not found. Also the answer when the caller is no longer a member of the organisation that owns the job's project. content: text/plain: schema: type: string '409': description: | The project's organisation has no owner to bill (`reason: orga_has_no_owner`; contact support), or the job cannot be retried as asked: it did not fail (and `force` was not set), it is still indexing, its project was deleted, or its grill stage cannot run (the body says why). It is also the answer when poma-core already converted the job (it has a job_archive row), `force` or not, and when a `force` retry of a job that was still running raced that run's end: the run finished while the retry was being queued, so the retry will not run (retry again if the job failed). For a job that run converted, a retry that had already started may run a second time. content: text/plain: schema: type: string application/json: schema: $ref: "#/components/schemas/ErrorResponse" '500': description: Server error content: text/plain: schema: type: string '503': description: Service temporarily unavailable. The check whether the caller may still read the job's organisation project could not be made. Retry later. content: text/plain: schema: type: string /health: get: summary: Get service health description: | Get the health of the service. **Description** This endpoint returns the health of the service. **Responses** | Status Code | Description | Content Type | | ----------- | ---------------------------------------------------------------- | ------------------- | | `200` | OK. Returns the health of the service. | application/json | | `500` | Server error | text/plain | operationId: health tags: - health security: [] responses: '200': description: OK content: application/json: schema: type: string example: "ok" '500': description: Server error content: text/plain: schema: type: string components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT parameters: XProjectID: in: header name: X-Project-ID required: false schema: type: string format: uuid description: > **Optional when using account-level credentials** (login token or account API key) on product routes. Specifies which project to use for namespace isolation, quota, and protection checks. Not needed when authenticating with a project API key — the key already identifies the project. When omitted with account credentials, the account's default project for the route's product is used; a 400 with `code: no_default_project` is returned if no default exists. XIncludeLinksSummary: in: header name: X-Include-Links-Summary required: false schema: type: boolean default: false description: > **Remote-URL (`X-Remote-URL`) ingestion only.** When `true`, appends Jina Reader's full link summary to the rendered markdown so footer / social / nav links survive readability extraction. Forwarded to poma-core as the `include_links_summary` parameter. No-op for non-URL ingests (raw body uploads). XFooterOnly: in: header name: X-Footer-Only required: false schema: type: boolean default: false description: > **Remote-URL (`X-Remote-URL`) ingestion only.** When `true`, restricts Jina Reader extraction to the page footer block, yielding a document of only the footer. Composes with `X-Include-Links-Summary`. Forwarded to poma-core as the `footer_only` parameter. If the footer selector matches nothing the job fails (no silent fallback). No-op for non-URL ingests. responses: GrillPaymentRequired: description: | Payment required. The payer's credits are exhausted (`reason: quota_exceeded`) or its index4ai storage cap is reached (`reason: storage_cap_exceeded`). On a project of an organisation that has no active index4ai subscription the work is refused before any credit check with `reason: orga_subscription_required` and the organisation's `orga_id` (the `error` text is the credit shortfall's, `quota exceeded`): the organisation needs its own index4ai subscription, buying credits does not help. An organisation whose index4ai subscription has ended answers `reason: quota_exceeded`. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: orgaSubscriptionRequired: value: {"error": "quota exceeded", "code": 402, "reason": "orga_subscription_required", "orga_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"} quotaExceeded: value: {"error": "quota exceeded", "code": 402, "reason": "quota_exceeded"} OrgaAccessUnavailable: description: >- The organisation access check (membership and manager reads) could not be read (`reason: orga_access_unavailable`). The request failed closed: it was refused without changing anything, and a retry later is safe. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" TooManyJobs: description: > Too many active jobs — the account is at its concurrent-job capacity (pending + processing). Capacity frees when an in-flight job completes, so retry after a short pause; the `Retry-After` header and `retry_after_seconds` body field carry a pacing hint (default 5s). This is the backpressure signal clients should throttle on. headers: Retry-After: description: Suggested seconds to wait before retrying. Heuristic pacing hint, not an exact deadline. schema: type: integer example: 5 content: application/json: schema: $ref: "#/components/schemas/TooManyJobsError" ResultBusy: description: > The result service is busy: too many large results are being read at the same time, so this request was refused instead of queued. Transient; it says nothing about the job or its results. Retry after the `Retry-After` delay (10 seconds by default, never more than 60). Only requests that return parsed JSON results read through the result service; an archive download never answers this. A HEAD request answers the same status and headers without a body. A result that is slow to fetch, rather than refused, still answers 500. headers: Retry-After: description: Seconds to wait before retrying, between 1 and 60. schema: type: integer example: 10 content: application/json: schema: $ref: "#/components/schemas/ResultBusyError" schemas: TooManyJobsError: # Extends the ErrorResponse envelope with retry_after_seconds. # BREAKING CHANGE (Phase 2): `message` renamed to `error` to align with ErrorResponse envelope. type: object properties: code: type: integer description: Mirrors the HTTP status code. enum: [429] example: 429 reason: type: string description: Machine-readable discriminator distinguishing this 429 from other rate limits. enum: [too_many_jobs] example: too_many_jobs error: type: string description: Role-aware, human-readable explanation of the active-job limit. example: Customer accounts can have 1000 active jobs at a time. Contact us to increase your limit. retry_after_seconds: type: integer description: Same value as the `Retry-After` header — suggested seconds before retrying. example: 5 required: [code, reason, error, retry_after_seconds] ResultBusyError: # Extends the ErrorResponse envelope with retry_after_seconds, same shape as TooManyJobsError. type: object properties: code: type: integer description: Mirrors the HTTP status code. enum: [503] example: 503 reason: type: string description: Machine-readable discriminator distinguishing this 503 from other unavailability answers. enum: [result_busy] example: result_busy error: type: string description: Human-readable explanation. example: result service busy, retry later retry_after_seconds: type: integer description: Same value as the `Retry-After` header — seconds to wait before retrying. example: 10 required: [code, reason, error, retry_after_seconds] LimitExceededError: # Extends ErrorResponse. Returned when a resource quota is hit. type: object description: Returned when a per-account or per-org resource limit is reached. required: - error - code - resource - limit - current properties: error: type: string description: Human-readable error message. example: "limit exceeded" code: type: integer description: Mirrors the HTTP status code. example: 403 reason: type: string description: Machine-readable discriminator. example: "limit_exceeded" resource: type: string description: | The resource type that hit its limit: `project`, `orga_project`, `orga_member`, `orga_membership` (the per-account organisation limit) or `orga_owned` (the number of live organisations an owner may own). limit: type: integer description: The maximum allowed count for this resource. example: 5 current: type: integer description: The current count of the resource. example: 5 JobInfo: type: object properties: job_id: type: string format: uuid description: Job identifier project_id: type: string format: uuid description: Project identifier the job belongs to filepath: type: string description: Original filename submitted by the user created_at: type: string format: date-time description: Job creation timestamp (UTC) status: type: string enum: [pending, processing] description: Current job status ActiveJobsResponse: type: object properties: pending: type: array items: $ref: "#/components/schemas/JobInfo" description: Jobs in pending status (up to `limit` items) processing: type: array items: $ref: "#/components/schemas/JobInfo" description: Jobs in processing status (up to `limit` items) total_pending: type: integer description: True count of pending jobs for the account (independent of the cap) total_processing: type: integer description: True count of processing jobs for the account (independent of the cap) AccountRegisterEmailRequest: type: object required: - email properties: email: type: string format: email description: Email address example: "johanna@poma-ai.com" username: type: string description: Username example: "john_doe" AccountRegisterOrgaUserRequest: type: object required: - orga_id - invite_key - email properties: orga_id: type: string description: The organisation's id invite_key: type: string description: The organisation's default invitation key example: "poma_orgainvite_..." email: type: string format: email description: Email address username: type: string description: Username OrgaInviteInfoRequest: type: object required: - orga_id - invite_key properties: orga_id: type: string description: The organisation's id invite_key: type: string description: The organisation's default invitation key example: "poma_orgainvite_..." OrgaInviteInfo: type: object properties: name: type: string description: The organisation's name example: "Acme" OrgaDefaultInviteKeyStatus: type: object properties: exists: type: boolean created_at: type: string format: date-time nullable: true OrgaDefaultInviteKey: type: object properties: invite_key: type: string description: The plaintext key. Returned only by the call that generates it. example: "poma_orgainvite_..." created_at: type: string format: date-time AccountVerifyEmailRequest: type: object required: - email - code properties: email: type: string format: email description: Email address example: "johanna@poma-ai.com" code: type: string description: Verification code sent to the email example: "123456" orga_id: type: string description: Only for a sign-up through `POST /registerOrgaUser`. The organisation to join. invite_key: type: string description: Only for a sign-up through `POST /registerOrgaUser`. The organisation's default invitation key. With `orga_id` it joins the account to the organisation as `member` once the code is accepted (it is checked against the current key; a failed join is not an error). example: "poma_orgainvite_..." AccountRegisterEmailResponse: type: object required: - token properties: token: type: string description: JWT authentication token returned after verification example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." api_key: type: string description: | A new non-expiring account API key. Present only when the request carried `orga_id` and `invite_key`, the account is a member of the organisation, had never logged in, had no API key and is not staff (an existing key is never replaced). Shown only here. example: "pk_live_abc123..." RefreshTokenRequest: type: object properties: refresh_token: type: string description: | Opaque refresh token obtained from login or a previous refresh. Optional: omit it to use the `poma_refresh_token` httpOnly cookie instead. example: "poma_rt_abc123..." RefreshResponse: type: object required: - token - refresh_token - access_token_expires_at properties: token: type: string description: New JWT access token example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." refresh_token: type: string description: New opaque refresh token (old one is now revoked) example: "poma_rt_def456..." access_token_expires_at: type: string format: date-time description: RFC3339 timestamp when the new access token expires example: "2026-06-05T07:45:00Z" LogoutRequest: type: object properties: refresh_token: type: string description: Optional refresh token. If provided, only this token's family is revoked; otherwise all sessions are revoked. example: "poma_rt_abc123..." AccountApiKeyResponse: type: object required: - api_key properties: api_key: type: string description: Opaque API key for use as a Bearer token. example: "pk_live_abc123..." GenerateProjectApiKeyRequest: type: object description: | Optional body for POST /projects/{projectId}/generateApiKey. An empty body (or omitted `expires_at`) means the generated key never expires. properties: expires_at: type: string format: date-time nullable: true description: | RFC3339 timestamp at which the key should expire. Omit or send `null` for no expiration. When set, the value must be in the future and within the server's maximum allowed lifetime. example: "2026-09-20T00:00:00Z" GenerateAccountApiKeyRequest: type: object description: | Optional body for POST /generateApiKey. An empty body (or omitted `expires_at`) means the generated key never expires. properties: expires_at: type: string format: date-time nullable: true description: | RFC3339 timestamp at which the key should expire. Omit or send `null` for no expiration. When set, the value must be in the future and within the server's maximum allowed lifetime. example: "2026-09-20T00:00:00Z" ApiKeyMeta: type: object required: - project_id - has_key - created_at properties: project_id: type: string format: uuid description: Project the key belongs to. example: "550e8400-e29b-41d4-a716-446655440000" has_key: type: boolean description: Always true for entries in the list (only projects with an active key appear). example: true created_at: type: string format: date-time description: When the active key was created (RFC3339). example: "2026-06-01T10:00:00Z" expires_at: type: string format: date-time nullable: true description: RFC3339 expiry; null means the key never expires. example: "2026-07-01T10:00:00Z" ApiKeyListResponse: type: object required: - keys - next_cursor properties: keys: type: array description: Metadata for each project (in this page) with an active API key for this account. items: $ref: "#/components/schemas/ApiKeyMeta" next_cursor: type: string nullable: true description: Opaque cursor for the next page; `null` when this is the last page. Pass back as the `after` query param. example: "42" PublicAccount: type: object required: - account_id - username - email - plan - api_key properties: account_id: type: string format: uuid description: Unique identifier for the account example: "550e8400-e29b-41d4-a716-446655440000" username: type: string description: Username example: "john_doe" email: type: string format: email description: Email address example: "john@poma-ai.com" plan: type: string description: Plan example: "free" api_key: type: string description: API key example: "1234567890" api_key_expires_at: type: string format: date-time nullable: true description: | Expiry of the (masked) `api_key`, RFC3339. Omitted or null means the key never expires. Present only when an account API key exists. example: "2026-09-20T00:00:00Z" role: type: string description: | Account role, lowest to highest: `demo`, `orga_user`, `customer`, `enterprise`, `member`, `dev`. Every role check is "at least" — a higher role satisfies a lower threshold. `orga_user` has exactly the rights of `demo` (created by `POST /registerOrgaUser`). `enterprise` carries exactly the same rights as `customer`; it differs only in its job-concurrency and orga/project limit tiers. Credit quotas are not role-dependent. enum: [demo, orga_user, customer, enterprise, member, dev] example: "customer" grill_subscription_type: type: string description: Active index4ai subscription plan identifier. Absent if no active index4ai subscription. example: "grill_packaged_monthly_starter" max_owned_orgas: type: integer description: Enterprise accounts. Override of the cap on live organisations the account may own (`0` or absent keeps the tier default, negative removes the cap). manager_writes_per_hour: type: integer description: Enterprise accounts. Override of the member, invitation and role writes per controlled manager per hour, for organisations the account owns (`0` is unlimited). grill_subscription_ends_at: type: string format: date-time description: Present only while the active index4ai subscription is scheduled to end (cancelled, still active until this date). Absent otherwise. AccountUsageResponse: type: object required: - grill properties: grill: $ref: "#/components/schemas/ProductUsage" chart: allOf: - $ref: "#/components/schemas/MyUsageChart" description: | Optional daily usage chart of index4ai usage: job types `grill`, `grill-light`, `datalake-grill`, `datalake-grill-light` (ingest) PLUS index4ai search, which is metered separately from jobs. The `grill.*` pools in this same response are quota counters with their own reset windows, not sums over a date range, so the chart will not add up to any pool's `used` value. The chart does not subtract usage covered by free credits — it is total consumption, not billed consumption. Each bucket also carries the breakdown into the two meters behind it: `credits_used_ingest` and `credits_used_search` sum to `credits_used`, up to float rounding — see the per-field notes, and do not assert exact equality. UsageChartBucket: type: object required: [start, credits_used] properties: start: type: string format: date-time description: | The bucket's inclusive lower bound: UTC midnight. `/myUsage` buckets are always whole UTC days, whatever `chartResolution` selects — the resolution sets the window length, not the bucket unit, and `unit` is always `day`. credits_used: type: number format: double description: | Credits consumed in this bucket. Fractional DISPLAY credits, the same unit as `total_credits_used`. example: 10.5 credits_used_ingest: type: number format: double description: | The JOB (ingest) part of `credits_used` — `job_archive` usage over whatever job types `chartProduct` selects. Present on `/myUsage` on EVERY bucket, including quiet ones, where it is `0`. Absent is never the same as `0`. Read `credits_used` for the bucket total. This field and `credits_used_search` are each divided from their own integer centcredit sum, so adding the two floats back together can land an ulp away from it. example: 3.0 credits_used_search: type: number format: double description: | The index4ai SEARCH part of `credits_used`, metered in its own table and never in `job_archive`. Same presence rule as `credits_used_ingest`: the two appear together or not at all, on `/myUsage` and only for the products that include search. Note the latency difference this makes visible. Search usage is recorded at request time; job usage counts only once the job is ARCHIVED, and is bucketed by the day the job was CREATED. In a recent bucket the two sides are therefore not equally settled — see the freshness note on `MyUsageChart`. example: 7.0 MyUsageChart: type: object required: [unit, from, to, buckets, credits_used_total] description: | Daily usage over a window ending now. Requested with `chart=true`; may be absent even then if the chart could not be built (see the `chart` query parameter). `unit` is always `day`. `chartResolution` selects the window, not the granularity. `from` is a UTC midnight and always equals `buckets[0].start`; `to` is the current instant and falls inside the LAST bucket, which is therefore the in-progress day and is partial. Every other bucket is a whole UTC day. Buckets are CONTIGUOUS — a day with no usage is present with `credits_used` 0, never omitted. Bucket count: 7 for `week`, 30 for `month`. `credits_used_total` is the sum of the buckets in display credits, computed server-side from integer centcredits after the buckets are built. Prefer it over summing client-side. **Freshness.** A job counts from the moment it is ARCHIVED but is bucketed by the day it was CREATED. So (a) jobs still in flight are missing from recent buckets, and (b) a job created Monday and archived Wednesday changes Monday's bucket after you have already fetched it — buckets are not immutable once read. An archived job with no usage record contributes 0 rather than being dropped. index4ai SEARCH usage has no such lag; it is recorded at request time, so in a `grill` or `all` chart the two halves of a recent bucket have different latencies. Empty-value query params are rejected: `?chart` with no value is a 400, not "off". (The admin usage endpoint reads an empty `chart` flag as absent; these two differ deliberately. Its `chartResolution` and `chartProduct` reject an empty value exactly as these do.) properties: unit: type: string enum: [day] description: Bucket granularity. Always `day` on this endpoint. example: day from: type: string format: date-time description: | Inclusive start of the charted window, always a UTC midnight and always equal to `buckets[0].start`. example: "2026-08-18T00:00:00Z" to: type: string format: date-time description: | The current instant. It falls INSIDE the last bucket, which is the in-progress UTC day and is therefore partial. example: "2026-09-16T12:00:00Z" buckets: type: array description: Oldest first, contiguous, one per whole UTC day in the window. items: $ref: "#/components/schemas/UsageChartBucket" credits_used_total: type: number format: double description: | Sum of every bucket in the window, in display credits. Computed after the buckets are built, from integer centcredits, so it cannot disagree with them. example: 13.56 ProductUsage: type: object required: - has_subscription - burst_ingest - burst_search - ingest_monthly - search_monthly - redundancy_rate properties: has_subscription: type: boolean description: Whether the account has an active index4ai subscription burst_ingest: $ref: "#/components/schemas/PoolUsage" description: Base account-quota ingest pool; non-resetting; always present. On `GET /myUsage`, for an active index4ai subscription that keeps its one-time burst on the subscription, the base pool plus that burst (used and total added). A personal project's usage route shows the base pool alone. The organisation usage routes (`GET /orgas/{orgaId}/usage`, an organisation project) show the burst on the organisation's subscription alone, since an organisation has no base pool. burst_search: $ref: "#/components/schemas/PoolUsage" description: Base account-quota search pool; non-resetting; always present ingest_monthly: $ref: "#/components/schemas/PoolUsage" description: Subscription ingest pool — resets monthly; zeroed when unsubscribed search_monthly: $ref: "#/components/schemas/PoolUsage" description: Subscription search pool — resets monthly; zeroed when unsubscribed redundancy_rate: type: [number, "null"] minimum: 0 maximum: 1 description: | Share (0-1) of index4ai ingest jobs finished in the current `ingest_monthly` window that were charged zero credits, meaning they were served from output already in the project (a cache hit). `null` when unsubscribed (the burst pools have no window) or when no job finished in the window. example: 0.25 PoolUsage: type: object required: - used - total properties: used: type: number description: Credits used (centcredits/100) example: 1.5 total: type: number description: Total credits available (centcredits/100) example: 10.0 period_start: type: string format: date-time description: Start of the current reset window; absent for burst_* pools and when unsubscribed period_end: type: string format: date-time description: End of the current reset window (next reset); absent for burst_* pools and when unsubscribed AccountUpdateRequest: type: object required: - username properties: username: type: string description: Username example: "john_doe" JobsSearchResult: type: object description: | Default Go JSON encoding uses exported struct field names (`Jobs`, `Total`, `Results`, `Page`, `PageSize`). properties: Jobs: type: array items: $ref: "#/components/schemas/ArchivedJob" Total: type: integer Results: type: integer Page: type: integer PageSize: type: integer ArchivedJob: type: object required: - job_id - account_id - created_at - status_code properties: id: type: integer format: int64 job_id: type: string format: uuid account_id: type: string format: uuid project_id: type: string format: uuid input_file_id: type: string input_file_path: type: string input_file_content_md5: type: string code: type: string created_at: type: string format: date-time completed_at: type: string format: date-time expires_at: type: string format: date-time status: type: string description: Job status string (e.g. done, failed) status_code: type: integer fail_expected: type: boolean origin: type: string description: Origin hint (webapp, sdk, api, cli, mcp, etc.) email: type: string usage: $ref: "#/components/schemas/JobUsageResponse" storage_released_at: type: string format: date-time description: >- When this job's pages were released from the index4ai storage stock they were charged to (the payer's subscription row or free pool) (per-doc delete, replacement by a newer conversion, or a dedup hit). Absent while the document still occupies storage. This and the fields below are projected by single-job and account-list lookups, not by the search endpoints. storage_release_reason: type: string enum: - doc_delete - replaced - dedup_hit - evicted - purge description: What released the storage. Present with storage_released_at. grill_deduplicated: type: boolean description: >- index4ai's verdict for this job: true = dedup hit (nothing new stored). Absent when index4ai has not reported for this row. grill_doc_id: type: string description: The document id that holds this job's content (see JobStatusResponse.grill.doc_id). grill_replaced_doc_ids: type: array items: type: string description: Documents index4ai evicted in favour of this job (see JobStatusResponse.grill.replaced_doc_ids). grill_evicted_doc_ids: type: array items: type: string description: Cross-mode duplicates index4ai cleaned up during this job (see JobStatusResponse.grill.evicted_doc_ids). PublicJob: type: object required: - job_id - created_at properties: job_id: type: string format: uuid description: Unique identifier for the job example: "550e8400-e29b-41d4-a716-446655440000" status: $ref: "#/components/schemas/JobStatusResponse" properties: $ref: "#/components/schemas/PublicJobProperties" created_at: type: string format: date-time description: Timestamp when the job was created example: "2021-01-01T00:00:00Z" notice: type: ["string", "null"] description: Set only when the request was repriced/rerouted. Says what happened and what to do. Absent otherwise. PublicJobProperties: type: object properties: file: $ref: "#/components/schemas/FileDetails" base_url: type: string description: Optional base URL to resolve image links example: "https://api.poma-ai.com" JobDownloadResponse: type: object required: - mime_type - size - download_url - expires_at properties: mime_type: type: string description: Archive MIME type example: "application/zip" size: type: integer format: int64 description: Archive size in bytes example: 1024 download_url: type: string description: Download URL example: "https://api.poma-ai.com/jobs/550e8400-e29b-41d4-a716-446655440000/download" expires_at: type: string format: date-time description: Expiration date example: "2024-01-01T00:00:00Z" converter_id: type: string description: >- Fingerprint of the poma-core build that produced this result (the deployed release tag, or a code+config hash for non-release builds). Two jobs on the same input with the same `converter_id` are a dedup hit in index4ai; a different value means the content is re-indexed and the earlier document replaced. Absent on results produced before this field existed. example: "v1.0.9" JobResults: type: object description: | Parsed content from the job’s POMA result archive: `chunks` and `chunksets`, plus `images`, `tables` and `code` when the document produced any. The same keys are returned whether the deployment runs a dedicated result service or reads the archive in-process; a result service with a custom `objectValues` configuration may add further keys. properties: chunks: type: array description: | Parsed chunk objects. The archive member is `chunks.json` on the `json` archive format (schema_version 2) or `chunks.jsonl` on `jsonl` (schema_version 3); both are returned under this key, so a client never branches on the format. items: {} chunksets: type: array description: | Parsed chunk sets, from `chunksets.json` or `chunksets.jsonl` depending on the archive format. Returned under this key either way. items: {} skipped_members: type: array description: | Members that were present in the archive but left out of this payload. Omitted entirely when nothing was skipped, so its presence means the payload is incomplete and an absent `chunks` array must not be read as "this document had no chunks". An entry for `metadata_content.json` (document metadata and conversion diagnostics) does not make the content incomplete; a bucket JSON delivery still goes out with that entry listed. `reason` is `too_large` when the member exceeded the per-member uncompressed-size cap — the data exists and GET `/jobs/{job_id}/download?type=archive` will serve it. The `type` is explicit because the default is operator-configured, and a `json` default routes through this same cap. `decode_failed` means the member could not be parsed, i.e. it is damaged. items: type: object required: - file - reason properties: file: type: string description: Archive entry name, e.g. `chunks.jsonl`. reason: type: string enum: [too_large, decode_failed] size_bytes: type: integer format: int64 description: Uncompressed size of the member. Only set for `too_large`. max_bytes: type: integer format: int64 description: The cap that refused it. Only set for `too_large`. metadata: type: object additionalProperties: true description: | Archive-level metadata from the POMA archive's zip comment (source file, source type, creation date, schema version). Returned on both result paths — the dedicated result service and the in-process archive read — so it is present whenever the archive has a comment and omitted entirely when it has none. A comment that is not a JSON object is returned as `{ "raw": "" }`. images: type: object additionalProperties: type: string description: | Maps image placeholder id (e.g. `image_00001`) to a base64 data-URI, read from the archive's `image_sources.json`. Returned on both result paths — the dedicated result service and the in-process archive read — and omitted entirely when the archive carries no such member, which is the case for a document that produced no images. tables: type: object additionalProperties: type: string description: | Maps table placeholder id (e.g. `table_00001`) to its content, read from the archive's `tables.json`. The value is HTML for `format=html` tables and markdown for `format=md`. Returned on both result paths, and omitted when the document produced no tables. code: type: object additionalProperties: type: string description: | Maps code placeholder id (e.g. `code_00001`) to its source, read from the archive's `code.json`. Returned on both result paths, and omitted when the document produced no code blocks. metadata_content: type: object additionalProperties: true description: | Document-level metadata from the conversion: title, canonical_url, detected language and conversion diagnostics, read from the archive's `metadata_content.json`. Present when the archive contains that member, omitted otherwise. additionalProperties: true JobStatusResponse: type: object required: - job_id - status - code properties: job_id: type: string description: Job ID example: "550e8400-e29b-41d4-a716-446655440000" status: type: string description: >- Status of the job. For index4ai jobs this covers both stages: the document is converted first and then indexed for search. `indexing` means the conversion finished and the indexing is still running — index4ai jobs only. An index4ai job therefore reports `done` only once the indexing has also succeeded, and can report `failed` when the conversion succeeded but the indexing did not. That failure carries the indexing stage's own code: 413 when the document was too large for the indexing pods (an operator can retry it with `stage=grill` once capacity is raised), 500 for any other indexing error, and 409 when no code was recorded. enum: - pending - processing - indexing - done - failed - blocked example: "done" code: type: integer description: >- Code of the job. A failure code mirrors the corresponding HTTP status where one applies. In particular a credit/quota shortfall always reports 402, whether it was caught before dispatch or by the processing backend. 402, 403, 413, 415 and 422 are expected failures (bad input or account state), not service incidents — except a 413 on an index4ai job that reached indexing (`failed` after the conversion succeeded), which means the document exceeded the indexing capacity, not that the input was invalid. example: 200 detail: type: object description: JSON object containing details about errors example: {"error": "File not found"} download: $ref: "#/components/schemas/JobDownloadResponse" description: >- Where to fetch the result archive. Present only once the result is actually retrievable from poma: absent while the job is still running, absent for the short span between the processing backend finishing and the result being stored, and absent for the whole life of an index4ai job, whose results are searched rather than downloaded. For a NON-index4ai job, therefore, `status: done` without a `download` block means "retry the status call shortly", not an error; for an index4ai job it is the final shape and will never grow one. `download_url` is always a poma URL of the form `{base}/jobs/{job_id}/download`. usage: $ref: "#/components/schemas/JobUsageResponse" grill: type: object description: >- index4ai's indexing outcome. Present only once the indexing stage has reported (index4ai jobs, status `done`); absent for other jobs and for jobs indexed by an older index4ai build. Absent means "no information", never "not deduplicated". required: - deduplicated - doc_id - replaced_doc_ids - evicted_doc_ids properties: deduplicated: type: boolean description: >- `true` when index4ai kept an existing document for this content instead of storing this job's chunks: nothing new was stored, `doc_id` names that existing document, and this job's pages do not occupy storage. Conversion credits are still consumed. example: false doc_id: type: string description: >- The document id that holds this content — this job's id normally, or the pre-existing document's id on a dedup hit. Use it for search filters and `DELETE /docs/{docId}`. example: "550e8400-e29b-41d4-a716-446655440000" replaced_doc_ids: type: array description: >- Documents replaced because this job re-indexed the same content under a newer conversion build. Their storage pages are released when the replaced document was a job of this account. Always an array, empty when nothing was replaced. Always empty when `deduplicated` is true — a duplicate stored nothing, so it replaced nothing. items: type: string example: [] evicted_doc_ids: type: array description: >- Duplicates of this content cleaned up during this job: a copy indexed in the other conversion mode, superseded by the document that `doc_id` names. Their storage pages are released when the evicted document was a job of this account. Unlike `replaced_doc_ids` this list can be non-empty alongside `deduplicated: true`. Always an array; empty on jobs that cleaned nothing up, and also on jobs finished before this field was recorded. items: type: string example: [] JobUsageResponse: type: object required: - credits - pages - tokens properties: credits: type: integer format: int64 description: Number of credits used example: 2048 pages: type: integer format: int64 description: Number of pages used example: 1024 tokens: type: integer format: int64 description: Number of tokens used example: 2048 FileDetails: type: object properties: filename: type: string description: File name example: "document.pdf" size: type: integer format: int64 description: File size in bytes example: 1024 SearchRequest: type: object required: - query properties: query: type: string description: Natural-language search query. doc_filter: type: string description: Optional document id filter. exclude_doc_ids: type: array items: type: string description: Document ids to exclude from search results. doc_ids: type: array items: type: string description: Restrict search to these document ids. return_assets: type: boolean description: "Return extracted figures/tables referenced by the included docs. Comes back in the response `assets` map keyed by doc_id (images are base64 data-URIs referenced as `[IMAGE: name]` in the context); empty when none." return_page_images: type: boolean deprecated: true description: "DEPRECATED / not yet available — currently a no-op. Full-page screenshots will be served via a dedicated page endpoint, never inline." format: type: string enum: [json, prompt_ready] description: Response format. `json` returns structured ranked hits; `prompt_ready` returns a rendered XML+Markdown context block. min_relevance: type: number format: float description: Minimum relevance score threshold (0–1). Hits below this are dropped from the context block. Omit to use the backend-calibrated default (≈0.3). target_tokens: type: integer minimum: 100 maximum: 500000 description: Soft token target — the typical answer size. The response is built best-first up to this budget. Must not exceed max_tokens (clamped down if it would). Default 5000. max_tokens: type: integer minimum: 100 maximum: 500000 description: Hard token ceiling the response may expand to only for tightly-clustered multi-doc results. If set below target_tokens, the soft target is clamped down to match — the hard ceiling always wins; it never raises the delivered size. Default 15000. min_top_relevance: type: number format: double description: Minimum relevance threshold for the top result. If the best hit scores below this, the entire result set is empty. expand_tightness: type: number format: double description: Controls how aggressively the engine expands context around hits (0–1). retrieval_tier: type: string description: Retrieval tier override (e.g. free, standard, premium). premium: type: boolean description: Enable premium retrieval features (reranking, etc.). meta_tags_any: deprecated: true type: array items: type: string description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter results to documents matching ANY of these labels. This is the canonical name; `labels_any` is accepted as an inbound alias. If both are sent, this one wins. meta_tags_all: deprecated: true type: array items: type: string description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter results to documents matching ALL of these labels. This is the canonical name; `labels_all` is accepted as an inbound alias. If both are sent, this one wins. attribute_filters: type: array maxItems: 32 description: >- Filters on typed attributes set at ingest. Clauses combine with AND, with each other and with every other filter field; OR within a clause is expressed by the `in` / `contains_any` operators. A filter naming an attribute the namespace has never used matches NOTHING rather than being ignored — silently dropping it would widen the result set. List the project's existing attributes with `GET /attributes` before declaring a new name; names are permanent. items: type: object required: [attr, op] properties: attr: type: string description: Attribute name as supplied at ingest. op: type: string description: >- Operator. Availability depends on the attribute's type: eq/ne/in/nin/glob/iglob on string; eq/ne/in/nin/lt/lte/gt/gte on int; lt/lte/gt/gte on float and datetime; eq/ne on bool; contains/contains_any/any_lt/any_gt on arrays; has_all_tokens/has_any_tokens on encrypted_text. An operator the type does not offer returns 400 naming the ones it does. value: description: >- Operand. A list for in/nin/contains_any. For has_all_tokens/has_any_tokens a plain search string, tokenized and HMAC'd exactly as the stored value was — matching is EXACT, with no stemming or stop-word removal on either side. labels_any: deprecated: true type: array items: type: string description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Alias for `meta_tags_any`. Kept because the published API and the Python SDK have always used this spelling. labels_all: deprecated: true type: array items: type: string description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Alias for `meta_tags_all`. Kept because the published API and the Python SDK have always used this spelling. meta_int_1_gte: deprecated: true type: integer format: int64 description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter by metadata integer field 1 (greater than or equal). meta_int_1_lte: deprecated: true type: integer format: int64 description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter by metadata integer field 1 (less than or equal). meta_int_2_gte: deprecated: true type: integer format: int64 description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter by metadata integer field 2 (greater than or equal). meta_int_2_lte: deprecated: true type: integer format: int64 description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter by metadata integer field 2 (less than or equal). unencrypted_strings_match: type: object additionalProperties: type: string example: source: "jira*" ticket: "PROJ-?" description: | Filter results to documents whose ingest-time `X-Unencrypted-Strings` match these key→glob-pattern entries. Case-insensitive Unix glob (`*`, `?`); no wildcard = exact match. Keys are normalized to lowercase to match ingest. SearchInDocRequest: type: object required: - query - doc_filter properties: query: type: string description: Natural-language search query. doc_filter: type: string description: Document id to restrict search to. exclude_doc_ids: type: array items: type: string description: Document ids to exclude from search results. doc_ids: type: array items: type: string description: Restrict search to these document ids. return_assets: type: boolean description: "Return extracted figures/tables referenced by the included docs. Comes back in the response `assets` map keyed by doc_id (images are base64 data-URIs referenced as `[IMAGE: name]` in the context); empty when none." return_page_images: type: boolean deprecated: true description: "DEPRECATED / not yet available — currently a no-op. Full-page screenshots will be served via a dedicated page endpoint, never inline." format: type: string enum: [json, prompt_ready] description: Response format. `json` returns structured ranked hits; `prompt_ready` returns a rendered XML+Markdown context block. min_relevance: type: number format: float description: Minimum relevance score threshold (0–1). Hits below this are dropped from the context block. Omit to use the backend-calibrated default (≈0.3). target_tokens: type: integer minimum: 100 maximum: 500000 description: Soft token target — the typical answer size. The response is built best-first up to this budget. Must not exceed max_tokens (clamped down if it would). Default 5000. max_tokens: type: integer minimum: 100 maximum: 500000 description: Hard token ceiling the response may expand to only for tightly-clustered multi-doc results. If set below target_tokens, the soft target is clamped down to match — the hard ceiling always wins; it never raises the delivered size. Default 15000. min_top_relevance: type: number format: double description: Minimum relevance threshold for the top result. If the best hit scores below this, the entire result set is empty. expand_tightness: type: number format: double description: Controls how aggressively the engine expands context around hits (0–1). retrieval_tier: type: string description: Retrieval tier override (e.g. free, standard, premium). premium: type: boolean description: Enable premium retrieval features (reranking, etc.). meta_tags_any: deprecated: true type: array items: type: string description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter results to documents matching ANY of these labels. This is the canonical name; `labels_any` is accepted as an inbound alias. If both are sent, this one wins. meta_tags_all: deprecated: true type: array items: type: string description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter results to documents matching ALL of these labels. This is the canonical name; `labels_all` is accepted as an inbound alias. If both are sent, this one wins. attribute_filters: type: array maxItems: 32 description: >- Filters on typed attributes set at ingest. Clauses combine with AND, with each other and with every other filter field; OR within a clause is expressed by the `in` / `contains_any` operators. A filter naming an attribute the namespace has never used matches NOTHING rather than being ignored — silently dropping it would widen the result set. List the project's existing attributes with `GET /attributes` before declaring a new name; names are permanent. items: type: object required: [attr, op] properties: attr: type: string description: Attribute name as supplied at ingest. op: type: string description: >- Operator. Availability depends on the attribute's type: eq/ne/in/nin/glob/iglob on string; eq/ne/in/nin/lt/lte/gt/gte on int; lt/lte/gt/gte on float and datetime; eq/ne on bool; contains/contains_any/any_lt/any_gt on arrays; has_all_tokens/has_any_tokens on encrypted_text. An operator the type does not offer returns 400 naming the ones it does. value: description: >- Operand. A list for in/nin/contains_any. For has_all_tokens/has_any_tokens a plain search string, tokenized and HMAC'd exactly as the stored value was — matching is EXACT, with no stemming or stop-word removal on either side. labels_any: deprecated: true type: array items: type: string description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Alias for `meta_tags_any`. Kept because the published API and the Python SDK have always used this spelling. labels_all: deprecated: true type: array items: type: string description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Alias for `meta_tags_all`. Kept because the published API and the Python SDK have always used this spelling. meta_int_1_gte: deprecated: true type: integer format: int64 description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter by metadata integer field 1 (greater than or equal). meta_int_1_lte: deprecated: true type: integer format: int64 description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter by metadata integer field 1 (less than or equal). meta_int_2_gte: deprecated: true type: integer format: int64 description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter by metadata integer field 2 (greater than or equal). meta_int_2_lte: deprecated: true type: integer format: int64 description: >- Deprecated (D157): use `attribute_filters` (typed attributes); still accepted; removal will be announced. Filter by metadata integer field 2 (less than or equal). unencrypted_strings_match: type: object additionalProperties: type: string example: source: "jira*" ticket: "PROJ-?" description: | Filter results to documents whose ingest-time `X-Unencrypted-Strings` match these key→glob-pattern entries. Case-insensitive Unix glob (`*`, `?`); no wildcard = exact match. Keys are normalized to lowercase to match ingest. RetrievalContext: type: object description: Response shape when `format` is `prompt_ready` (the default). required: - context - query - namespace - result_count - tokens_estimated - results_dropped properties: context: type: string description: Prompt-ready XML+Markdown block with `` wrappers, gap markers, sandwich ordering, and token budgeting applied. Drop directly into an LLM prompt — no further processing needed. query: type: string description: The query as submitted, echoed back. namespace: type: string description: Namespace the search ran against. result_count: type: integer description: Number of documents included in `context`. tokens_estimated: type: integer description: Estimated token count of `context`. results_dropped: type: integer description: Hits that matched but were trimmed to fit the token budget. detected_lang: type: ["string", "null"] description: BM25 language index4ai detected for the query (canonical name, e.g. `english`). Null on low-confidence detection. mode: type: string description: Retrieval mode index4ai used. Passed through verbatim; index4ai owns the value set. search_units: type: integer description: Search units billed for this call. assets: type: object additionalProperties: true description: "Present only when `return_assets=true` and an included doc has figures/tables. Keyed by doc_id → `{images, tables}`; images are base64 data-URIs referenced as `[IMAGE: name]` in `context`. Omitted when nothing was requested or found." SearchResponse: type: object description: Response shape when `format` is `json` — raw ranked hits instead of a rendered context block. required: - results - query - namespace - result_count properties: results: type: array items: $ref: "#/components/schemas/SearchResult" description: Ranked per-document cheatsheets, already filtered by `min_relevance` and trimmed to fit the token budget. query: type: string description: The query as submitted, echoed back. namespace: type: string description: Namespace the search ran against. result_count: type: integer description: Number of entries in `results`. detected_lang: type: ["string", "null"] description: BM25 language index4ai detected for the query (canonical name, e.g. `english`). Null on low-confidence detection. results_dropped: type: integer description: Hits that matched but were trimmed to fit the token budget. mode: type: string description: Retrieval mode index4ai used. Passed through verbatim; index4ai owns the value set. search_units: type: integer description: Search units billed for this call. SearchResult: type: object description: One ranked per-document cheatsheet. required: - doc_id - chunkset_index - content properties: doc_id: type: string chunkset_index: type: integer description: Always `-1` — a cheatsheet spans multiple chunksets. content: type: string description: The cheatsheet text for this document. to_embed: type: string description: Text variant used for embedding, when index4ai returns it. pages: type: array items: type: integer description: Source page numbers covered by `content`. chunk_indices: type: array items: type: integer description: Indices of the chunks that were merged into `content`. title: type: string canonical_url: type: string maxLength: 2048 description: Citation URL stamped at ingest. Absent when none was supplied. score: type: number format: double description: Final ranking score after fusion and reranking. scores: $ref: "#/components/schemas/SearchScores" assets: description: Figures/tables for this hit, present only when `return_assets=true`. Passed through verbatim; index4ai owns the shape. page_images: description: Page images for this hit, present only when `return_page_images=true`. Passed through verbatim; index4ai owns the shape. SearchScores: type: object description: Per-stage scores for one hit. Each is omitted when the stage did not run. properties: ann: type: number format: double description: Approximate-nearest-neighbour (vector) score. bm25: type: number format: double description: BM25 keyword score. rrf: type: number format: double description: Reciprocal-rank-fusion score combining `ann` and `bm25`. reranker: type: number format: double description: Cross-encoder reranker score. ListAttributesResponse: type: object required: [attributes, max_names] properties: attributes: type: array items: type: object required: [name, type] properties: name: type: string example: region type: type: string description: POMA type, e.g. string, []string, int, float, bool, datetime, encrypted_text, []encrypted_text. example: string max_names: type: integer description: Per-project budget of attribute names. example: 64 note: type: string ListDocsResponse: type: object required: - documents - namespace - total_documents - has_more - degraded properties: documents: type: array items: $ref: "#/components/schemas/DocInfo" namespace: type: string total_documents: type: integer description: True full-namespace document count (never the page size). has_more: type: boolean description: True when more documents exist beyond this page (pass `next_cursor` to continue). next_cursor: type: ["string", "null"] description: Opaque cursor for the next page; null/absent when `has_more` is false. degraded: type: boolean description: True when at least one document in this page failed a transient fetch and was skipped. notice: type: ["string", "null"] description: Hint set only on truncated legacy-mode responses (no limit/cursor supplied and the namespace exceeds the default page size) — says how many documents exist and how to page through the rest. Absent for paging-aware callers. DocInfo: type: object required: - doc_id properties: doc_id: type: string title: type: string language: type: string filename: type: string canonical_url: type: string maxLength: 2048 description: Citation URL stamped at ingest and forwarded to poma-core, so downstream consumers can cite the original document. Absent when none was supplied. pages: type: integer chunkset_count: type: integer chunk_count: type: integer image_count: type: integer table_count: type: integer ingested_at: type: string source_job_id: type: string bm25_state: type: string description: State of the document's BM25 keyword index, as reported by index4ai. Passed through verbatim; index4ai owns the value set. attributes: type: object description: Typed attributes exactly as supplied at ingest — the verbatim customer map, including any array structure the index flattens. Present only when the document has any. Encrypted values are returned to their owner in the clear; they are unreadable only to the vector database. meta_tags: type: array items: type: string description: Labels as supplied at ingest, normalised. attribute_schema: type: object additionalProperties: type: object additionalProperties: type: string description: >- POMA type of each attribute above, as `{name: {"type": t}}` — the same shape the write path accepts, so a read round-trips into a write. Scoped to this document names, not the namespace whole vocabulary. Empty means the types are UNKNOWN (none declared, or the schema read failed), never that nothing is encrypted: `encrypted_text` and `string` are indistinguishable by value, which is why neither is inferred on write. UpdateDocAttributesRequest: type: object description: >- Attribute patch for one document. At least `attributes` must be present; `attribute_schema` alone is rejected, because a declaration must name an attribute the same request sets. required: - attributes properties: attributes: type: object additionalProperties: true description: >- Names to set, update or remove. A name with a value is written; a name whose value is `null` is REMOVED; a name not present here is untouched. Removing a value does not free the NAME — names are permanent for the namespace and keep counting against its budget. example: region: apac reviewed_at: "2026-09-21T07:30:00Z" obsolete_key: null attribute_schema: type: object additionalProperties: type: object properties: type: type: string enum: [string, "[]string", int, "[]int", float, "[]float", bool, "[]bool", datetime, "[]datetime", encrypted_text, "[]encrypted_text"] description: >- Types for attributes this document is the first in the namespace to use. Required for `datetime` and `encrypted_text`, which are never inferred. Every name declared here must also appear in `attributes`. Declaring a name that already has a type is what produces `attribute_type_conflict`. example: reviewed_at: type: datetime UpdateDocAttributesResponse: type: object required: - doc_id - attributes - attribute_schema properties: doc_id: type: string attributes: type: ["object", "null"] additionalProperties: true description: >- The document's FULL attribute map after the merge, not the slice the request carried. `null` when the write applied but reading the document back failed — refetch then. `{}` is a real answer meaning the document has no attributes left; it is NOT the same as `null`. attribute_schema: type: ["object", "null"] additionalProperties: type: object additionalProperties: type: string description: >- The POMA type of each attribute above, as `{name: {"type": t}}`. `{}` means the types are UNKNOWN, never that nothing is encrypted. `null` carries the same meaning as a null `attributes` — the read-back failed. DeleteDocResponse: type: object required: - doc_id - vectors_deleted - storage_deleted properties: doc_id: type: string vectors_deleted: type: integer storage_deleted: type: boolean Orga: type: object properties: orga_id: type: string format: uuid description: Unique organisation identifier. name: type: string description: Organisation display name. caller_role: type: string enum: [admin, member] description: | Role of the authenticated caller in this organisation. Present when the endpoint returns orgs scoped to the caller and the caller is a member: absent for a manager or owner without a membership. The `owner` membership role is retired (migration 097): the former owners hold `admin`. owner_account_id: type: string format: uuid description: The organisation's owner. It does not pay for the organisation's work; only an organisation subscription does. Never changes. Absent while an organisation has no owner (staff repair it). manager_account_id: type: string format: uuid description: The organisation's manager. It may be the owner. Absent while an organisation has no owner (staff repair it). caller_is_owner: type: boolean description: Whether the authenticated caller is the organisation's owner. Set on the endpoints that are scoped to the caller. caller_is_manager: type: boolean description: Whether the authenticated caller is the organisation's manager. Set on the endpoints that are scoped to the caller. manager_email: type: string format: email description: Email of the manager. Present for an owner caller only. created_at: type: string format: date-time updated_at: type: string format: date-time deleted_at: type: - string - 'null' format: date-time description: Set when the organisation is soft-deleted. Null for active organisations. SetOrgaManagerRequest: type: object required: - email properties: email: type: string format: email description: Email address of the account to make manager. It must have role `enterprise`, or be the caller itself. OrgaSubscription: type: object required: [subscription_id, role, product, type, state, subscribed_at, orga_id] properties: subscription_id: type: string format: uuid role: type: string enum: [holder, manager] description: "`holder`: the caller owns the organisation and pays. `manager`: the caller manages it." product: type: string enum: [grill] type: type: string description: Plan lookup key of the subscription. example: poma_grill_packaged_monthly_professional state: type: string enum: [active, scheduled_to_end, ended] subscribed_at: type: string format: date-time subscription_ends_at: type: string format: date-time description: Present when the subscription is scheduled to end or has ended. orga_id: type: string format: uuid synced_at: type: string format: date-time description: When Stripe last confirmed the row. OrgaSubscriptionRequest: type: object additionalProperties: false required: [product, intent] properties: product: type: string enum: [grill] intent: type: string enum: [buy, change] OrgaSubscriptionRequestAccepted: type: object required: [status, sent_at, next_request_at] properties: status: type: string enum: [sent] sent_at: type: string format: date-time next_request_at: type: string format: date-time description: When the same product may be requested again. ResignOrgaManagerRequest: type: object properties: leave: type: boolean default: false description: Also remove the resigning account's membership of the organisation, in the same transaction. RateLimitedError: allOf: - $ref: "#/components/schemas/ErrorResponse" - type: object description: A rate limit was hit (`reason` is `rate_limited`). The `Retry-After` header carries the wait in seconds. properties: limit: type: string enum: [manager_writes, manager_lookup] retry_after_seconds: type: integer MeResponse: allOf: - $ref: "#/components/schemas/PublicAccount" - type: object properties: can_create_orga: type: boolean description: | Whether the account may create or restore organisations: role `enterprise`, `member` or `dev`. The console shows its create button on this. example: false orga_subscriptions_enabled: type: boolean description: | Whether organisation subscriptions are switched on for the deployment (`billing.orgaSubscriptions.enabled`), the same for every account. While `false` an organisation checkout or switch answers `409 integrator_checkout_not_available`; `true` does not promise a checkout (`409 product_not_available` for primecut, `409 release_gate_closed` remain possible). The console shows the organisation checkout on this. example: false enterprise_request_status: type: string enum: [pending] description: | `pending` while the account's request for an enterprise account (`POST /requestEnterprise`, `POST /registerEnterprise`) waits for staff. Omitted when there is no open request, and for accounts that are already `enterprise` or higher. The requester gets a mail when staff grant the request. example: pending OrgaSearchResult: type: object description: Paginated-shape result; listing endpoints may return all rows in one response. properties: orgas: type: array items: $ref: "#/components/schemas/Orga" total: type: integer results: type: integer page: type: integer page_size: type: integer OrgaMember: type: object properties: orga_id: type: string format: uuid account_id: type: string format: uuid email: type: string format: email role: type: string enum: - owner - admin - member created_at: type: string format: date-time OrgaMembersListResponse: type: object required: - members properties: members: type: array items: $ref: "#/components/schemas/OrgaMember" OrgaInvitation: type: object properties: id: type: integer format: int64 description: Numeric invitation ID. orga_id: type: string format: uuid inviter_account_id: type: string format: uuid invitee_email: type: string format: email status: type: string enum: [pending, accepted, cancelled, expired] accepted_by_account_id: type: ['string', 'null'] format: uuid expires_at: type: string format: date-time resend_count: type: integer description: Number of times the invitation email has been resent (max 3). last_resent_at: type: ['string', 'null'] format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time CreateOrgaRequest: type: object required: - name properties: name: type: string minLength: 1 maxLength: 200 description: | Organisation name. Leading and trailing whitespace is trimmed; the trimmed name is 1 to 200 characters (counted as characters, not bytes) and holds no control character, no line separator and no invisible formatting character other than the zero width non-joiner and joiner and the left-to-right and right-to-left marks (`400 invalid_request` otherwise). manager_email: type: string format: email description: | Email of the account that manages the organisation. Optional: without it the caller manages it. The account must have role `enterprise` or be the caller itself (`404 manager_not_eligible` otherwise). UpdateOrgaRequest: type: object required: - name properties: name: type: string minLength: 1 maxLength: 200 description: | Organisation name. Leading and trailing whitespace is trimmed; the trimmed name is 1 to 200 characters (counted as characters, not bytes) and holds no control character, no line separator and no invisible formatting character other than the zero width non-joiner and joiner and the left-to-right and right-to-left marks (`400 invalid_request` otherwise). AddOrgaMemberRequest: type: object required: - email - role properties: email: type: string format: email description: Email address of the account to add. role: type: string enum: - owner - admin - member description: | Role to assign. `owner` is retired and never granted here (`400 orga_role_retired`). Changing the role of an account that is already a member is the manager's on this route (an admin gets `403`); an admin may add accounts and re-send an existing role, and changes a role through `PUT /orgas/{orgaId}/members/{accountId}/role`. Project: type: object properties: id: type: string format: uuid description: Internal project UUID account_id: type: string format: uuid description: Account ID that owns the project. For an organisation project it is the organisation's owner (the payer), not the creator, and it grants no access; only members of the organisation reach the project. For a personal project it is the creator. An organisation without an owner keeps the creator here orga_id: type: - string - "null" format: uuid description: Organisation ID (null for personal projects) project_id: type: string description: Client-facing project identifier name: type: string description: Display name product: type: string enum: - grill created_at: type: string format: date-time storage_base: type: string description: Storage base path protected: type: boolean description: > When true, account-level credentials are rejected for this project's product routes. Only project API keys are accepted. Defaults to false for personal projects, true for org projects. is_default: type: boolean readOnly: true description: | Whether this is a default project (auto-created, cannot be deleted or modified). An account's default project has no `orga_id` and is the implicit target of a request without `X-Project-ID`. The index4ai default of an account created through this API is named `Default Index`; an account created through the POMA API keeps its default named `Default Workspace`. A default is never renamed. Every new organisation also gets an unprotected default index4ai project named `Default Index` (`is_default: true` with its `orga_id`): organisation members reach it with an account credential that names it in `X-Project-ID`, or with a project API key, like any unprotected organisation project (membership alone decides; the organisation's owner has no special access). It is never the implicit target of a request without `X-Project-ID`, it is deleted and restored with its organisation and counts against the organisation's project limit. Its name is reserved inside the organisation. deleted_at: type: - string - "null" format: date-time description: Soft-delete timestamp (null for active projects) purge_claimed_at: type: - string - "null" format: date-time description: > Retention cleanup claimed this deleted project (state `purging` until `purged_at` is set after it). Only present on deleted projects; restore is refused while set without a later `purged_at`. purged_at: type: - string - "null" format: date-time description: > Retention cleanup completed: index4ai documents and storage pages are gone. Kept as history after a restore, so an active project may carry it. RestoredProject: description: The restored project, plus whether it came back empty. allOf: - $ref: "#/components/schemas/Project" - type: object required: - data_purged properties: data_purged: type: boolean description: > True when retention cleanup ran while the project was deleted: it is restored as an empty project (documents and storage pages were released). CreateProjectRequest: type: object required: - product - name properties: name: type: string maxLength: 64 description: | Display name for the project, at most 64 characters. Control characters and invisible format characters are refused with `400`. orga_id: type: string format: uuid description: | When set, creates an organisation-scoped project. Omitted, `null` or an empty string creates a personal project. A value that is not a uuid is refused with `400`. product: type: string enum: - grill CreateProjectResponse: type: object required: - project - api_key properties: project: $ref: "#/components/schemas/Project" api_key: type: string description: One-time member project API key (shown only on create) ErrorResponse: # BREAKING CHANGE (Phase 2): `code` was string, now integer (mirrors HTTP status). # Clients that compared code as a string must update to numeric comparison. type: object description: | Standard error envelope returned by all API error responses. Example: `{"error": "quota exceeded", "code": 402, "reason": "quota_exceeded"}` required: - error - code properties: error: type: string description: Human-readable error message. example: "too many active jobs" code: type: integer description: Mirrors the HTTP status code. example: 429 reason: type: string description: Machine-readable snake_case discriminator. Present when multiple errors share the same HTTP status code to allow programmatic distinction. example: "too_many_jobs" orga_id: type: string format: uuid description: | The organisation that needs a subscription; present only with `reason: orga_subscription_required` (`402` on index4ai work, `409` on `PATCH /projects/{projectId}/orga`).