Regnora's public API is a small document data plane with one door into the app: push files in, poll until they are processed, pull them back out as Word or Markdown, and open an Assistant chat over a user's files that a login link drops them straight into. Everything else, such as analysis, revision and agents, happens in the app.

## Authentication

An organization owner or admin creates API keys under **Settings → API keys**. The raw key is shown once, at creation. Send it as a bearer token on every request:

```http
Authorization: Bearer rk_live_…
```

A key acts as the whole organization, with no user attached. Documents it pushes without `user` are attributed to the person who created the key. Keys are stored hashed and transmitted over HTTPS only; revoking a key in settings takes effect on the next request, and each use records a last-used time. The boundaries a key and a login link operate within are summarised in the [security model](/integrate/quick-start/#security-model).

## Endpoints

The base URL is `https://api.regnora.com/api/integrations/v1`. The interactive reference and the OpenAPI document, from which you can generate a client, are served alongside:

- `/api/integrations/v1/docs`
- `/api/integrations/v1/openapi.json`

| Method and path | What it does |
| --- | --- |
| `POST /documents` | Push a document (multipart: `file`, optional `external_ref`, optional `project_id`). Answers `202` and starts processing. |
| `POST /documents/{id}/versions` | Push an updated file as the next version of an existing document. |
| `GET /documents/{id}` | Processing status: `{ id, status, external_ref, version }`. |
| `GET /documents/{id}/export.docx` | Download the current version as Word. |
| `GET /documents/{id}/export.md` | Download the current version's processed content as Markdown. |
| `POST /sessions` | Open an Assistant session for one of your users (multipart: `user`, optional `files`, `document_ids`, `prompt`). Answers `202` with a login link. |
| `GET /sessions/{id}` | The session's status and documents, with a fresh login link. |
| `POST /sessions/{id}/documents` | Push more files for the session's user, or attach documents already in their workspace. |
| `GET /sessions?user=` | A user's sessions, each with a fresh login link. |

Pushed documents land in the organization's default project unless `project_id` names another one, or `user` names one of your users (see below). `external_ref` is your own identifier for that version; it is stored and echoed back. Pushing a file whose bytes were already pushed into the same project answers `200` with the existing document instead of creating another.

`status` is `processing`, `ready` or `failed`, and describes the most recently pushed version. `version` is the number of the version exports serve, which moves once a new version finishes processing. Treat unknown status values as `processing`; the set may grow.

Supported file types are Word, PDF, Excel, CSV, Markdown and plain text, up to 50 MB.

## Sessions for your users

`POST /sessions` takes an email in `user` and opens an Assistant chat for that person. The first call for an email creates their Regnora account and a private workspace that only they can see; Regnora sends them no email. `files` are pushed into that workspace, `document_ids` must already be in it (pushed earlier with `user`, or through another session), and both are attached to the chat. With a `prompt` the Assistant starts answering right away; without one the chat waits for the user.

The response is `{ session_id, status, url, documents }`. `url` signs the user in without a password and opens the chat. It is a credential: it works for 20 minutes, more than once, for anyone who has it, so send it only to that user over a channel you trust. Once opened it starts a 24-hour app session. Every read of a session mints a new one, so fetch `GET /sessions/{id}` when you need a fresh link. `status` is `processing` while the Assistant answers, `awaiting_input` when it is the user's turn.

By creating a session or pushing for a user you confirm that the user has accepted Regnora's terms and privacy policy. An email that already belongs to a Regnora account with access of its own, such as a member of your organization, answers `409 user_not_exclusive`: a login link for that account would open more than their workspace.

## Errors

Every error is JSON with a stable `code`, a human-readable `message` and a `request_id` to quote when contacting support:

```json
{ "code": "not_found", "message": "Document not found", "request_id": "…" }
```

Codes include `unauthorized` (401), `insufficient_credits` (402), `forbidden` (403), `not_found` (404), `conflict`, `document_processing` and `user_not_exclusive` (409), `file_too_large` (413), `unsupported_file_type` (415), `validation_error` and `unprocessable` (422) and `rate_limited` (429, with a `Retry-After` header).

`insufficient_credits` means the organization has no credits left for the Assistant to answer a session's prompt; top up in the app and retry. `unprocessable` answers a document push that names both `user` and `project_id`.

A version push answers `conflict` while an earlier change to that document is still awaiting approval in Regnora; approve or reject it there, then push again. `document_processing` means the document has nothing to export yet: poll its status until it is `ready`.

If your integration needs more than this, [get in touch](/resources/support/).