API Documentation

The Regunow API uses HTTPS, Bearer authentication, and the versioned prefix /api/v1. You can read this documentation without an account. Making API requests requires active Pro access and acceptance of the current policies.

1. Sign in to Regunow and create a key in Settings → API Keys.
2. Save the secret securely. It is displayed once when you create the key.
3. Set your host and key, then send your first question from a backend or trusted automation.

# Use your Regunow host and a key from Settings → API Keys.
export REGUNOW_BASE_URL="https://YOUR_REGUNOW_HOST"
export REGUNOW_API_KEY="YOUR_API_KEY"

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-question-001" \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Which EU product-safety obligations apply to a connected consumer device?"
    }],
    "mode": "jurisdiction",
    "jurisdiction": "eu"
  }'

The answer is in output.content. Source references and the charged credits are included in the response. This request consumes credits. Use a new idempotency key for each new question.

// Node.js: set REGUNOW_BASE_URL and REGUNOW_API_KEY in your environment.
// Generate one key per operation; keep it unchanged when retrying that operation.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();
const response = await fetch(
  process.env.REGUNOW_BASE_URL + "/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.REGUNOW_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: "Summarize EU product-safety obligations." }],
      mode: "jurisdiction",
      jurisdiction: "eu",
    }),
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error.code + ": " + result.error.message);
}
console.log(result.output.content);

Send your API key in the HTTP Authorization header on every request. Keys in URLs, cookies, or request bodies are not accepted.

Authorization: Bearer rgn_live_...

Store keys in an environment variable or secret manager. Keep them out of browser code, mobile app bundles, public repositories, and logs. Cross-origin browser access is not enabled; make requests through your server.

Disabled, deleted, or expired keys stop authenticating immediately. Regunow stores only a hash of the secret, so an existing secret cannot be shown again. Create a replacement key when you need one.

Pro access and policy acceptance are checked on each request. If you receive legal_acceptance_required, the key owner must sign in and open Legal acceptance. An API key cannot accept policies.

GET/api/v1/models

Discover supported models, effort levels, jurisdictions, response languages, and capabilities. This authenticated endpoint has no separate credit charge and is a useful way to verify a key before making a completion request.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

Use values returned by the catalog for your deployment. In Jurisdiction mode, omit model and effort to use the accepted defaults. If you supply them, they must be the default Sonnet 4.6 / High selection. For answers without attachments, the retrieval service manages the answer model; the response's model field describes the validated selection.

POST/api/v1/chat/completions

Send a JSON body containing a messages array. By default, the API returns a complete answer as JSON. Set stream to true for incremental text.

{
  "messages": [{
    "role": "user",
    "content": "What retention period does this policy specify? Cite the document."
  }],
  "mode": "freestyle",
  "web_search": "off",
  "response_language": "en",
  "file_ids": ["YOUR_FILE_ID"]
}

Replace YOUR_FILE_ID with the UUID returned by a successful upload. Send relevant user and assistant history on each follow-up, and resend any file_ids you want to include. The API does not automatically remember conversation history or attachments.

System messages and unknown fields are rejected. Image generation, report generation, audio input, and saved-memory access are not exposed by this API. Uploaded images are supported as input for questions.

A successful completion returns object: "regunow.chat.completion", the answer, source metadata, usage, and timing. The following values are illustrative.

{
  "id": "request-uuid",
  "request_id": "request-uuid",
  "object": "regunow.chat.completion",
  "created": 1790812800,
  "model": "jp.anthropic.claude-sonnet-4-6",
  "latency": {
    "time_to_first_token_ms": 2345,
    "time_to_answer_completion_ms": 9876
  },
  "output": {
    "input_files": [],
    "role": "assistant",
    "content": "The complete answer...",
    "finish_reason": "end_turn",
    "citations": [],
    "sources": [],
    "web_search": false
  },
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 456,
    "charged_microcredits": 789000,
    "charged_credits": 0.789
  }
}

• output.content contains the canonical answer text. Citation offsets refer to this final string; sourceIndexes identifies entries in output.sources.
• Sources include their title, file name, MIME type, URI, and retrieved excerpt. Display excerpts and citations alongside the answer.
• A source URI is a locator and may point to private storage. Treat only public publisher URLs as links users can open; the API does not expose regulatory source-file downloads or translation.
• When attachments are used, output.input_files identifies the supplied files. Attachment sources have a file_id; regulatory and web sources have file_id: null. Attachment URIs are null.
• An input file's presence does not prove that it supports every statement. Models may omit inline citations, and images or scans may have empty excerpts.

Token counts can be null when the retrieval service does not expose them; this means unknown, not zero. charged_credits is the recorded customer charge. created is a Unix timestamp in seconds; latency values are milliseconds.

Every endpoint response carries an X-Request-Id header. Keep that identifier for troubleshooting. Completion and error JSON also contain request_id.

Set "stream": true. The response uses text/event-stream. With cURL, add -N to disable output buffering.

curl --fail-with-body -N \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: streaming-question-001" \
  -d '{
    "messages": [{"role":"user","content":"Summarize EU product-safety obligations."}],
    "mode": "jurisdiction",
    "jurisdiction": "eu",
    "stream": true
  }'

Read complete SSE events separated by blank lines; a network chunk may contain part of an event or several events. Append choices[0].delta.content as it arrives. Ignore comment heartbeats beginning with :.

data: {"choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{"content":"The answer begins..."},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"choices":[],"usage":{"prompt_tokens":1234,"completion_tokens":456,"total_tokens":1690},"regunow":{"output":{},"latency":{},"usage":{"charged_credits":0.789,"charged_microcredits":789000}}}

data: [DONE]

The final metadata event has an empty choices array. Read the canonical answer, citations, and sources from regunow.output, timings from regunow.latency, and credits from regunow.usage. Token counts use usage.prompt_tokens and usage.completion_tokens.

Retrieval and citation processing can introduce pauses. Treat text as provisional until the final metadata arrives. An error after streaming begins arrives as an error object followed by [DONE]; an HTTP 200 alone does not establish success. Earlier authentication or validation failures return ordinary JSON error responses.

A completed replay remains SSE and returns the stored answer as one text chunk with X-Idempotent-Replayed: true.

Upload documents or images, then attach their IDs to a completion. Files share the key owner's Library and storage quota. Documents can be up to 10 MiB; images up to 5 MiB.

Direct upload (recommended)

This three-step flow sends the original file bytes directly to storage, avoiding application request-body limits. Use it for hosted integrations, especially larger files.

POST/api/v1/files/upload-intents

Send only name, mime_type, and bytes (the exact file size). A successful request returns HTTP 201 with a pending file ID and a signed upload URL valid for 300 seconds.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/upload-intents" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-intent-001" \
  -d '{"name":"policy.txt","mime_type":"text/plain","bytes":16384}'

{
  "id": "YOUR_FILE_ID",
  "status": "pending",
  "upload_method": "PUT",
  "upload_url": "SIGNED_UPLOAD_URL",
  "upload_headers": {"Content-Type": "text/plain"},
  "expires_in": 300
}

Set FILE_ID to the returned id. Use the returned upload_method, upload_url, and upload_headers to upload the exact original bytes. Set the exact Content-Length. Do not send the Regunow API key to the upload URL, and keep signed URLs out of logs.

# Set UPLOAD_URL from the intent response. Use its returned upload_headers.
# This example assumes policy.txt is exactly 16,384 bytes.
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: text/plain" \
  -H "Content-Length: 16384" \
  --data-binary @./policy.txt

POST/api/v1/files/{fileId}/complete

Send {} with a different idempotency key. Completion validates the bytes and returns HTTP 200 with an available file. You can use its ID in file_ids only after completion succeeds.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/$FILE_ID/complete" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-complete-001" \
  -d '{}'

If the upload URL expires, delete the unused pending file and prepare another intent with a new key. Replaying an intent does not extend the URL's expiry. After an uncertain completion, retrieve the file's status first. If it is still pending, retry completion with a new idempotency key; the old key replays its stored outcome. Completing an already available file returns its metadata.

Multipart upload

POST/api/v1/files

For smaller files, send one multipart/form-data field named file. Send original bytes, not base64 or a remote URL. Your hosting gateway may impose a smaller body limit than the API's file allowance.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Idempotency-Key: policy-upload-001" \
  -F "file=@./policy.pdf;type=application/pdf"

A successful upload returns HTTP 201 with an available file; no separate completion call is needed.

{
  "id": "YOUR_FILE_ID",
  "object": "regunow.file",
  "name": "policy.pdf",
  "mime_type": "application/pdf",
  "category": "file",
  "bytes": 16384,
  "status": "available",
  "created_at": "2026-10-01T00:00:00Z",
  "request_id": "request-uuid",
  "usage": {"charged_microcredits":500,"charged_credits":0.0005}
}

List, retrieve, and delete files

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files?limit=20" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

Keys for the same account can access that account's available Library files. Missing files and files belonging to another account both return 404. If your application serves multiple users through one account, enforce your own user permissions before attaching or deleting files.

Pending and failed uploads occupy quota until cleanup succeeds. Incomplete uploads older than 24 hours are eligible for cleanup. An available file has passed upload validation; extraction happens when you ask a question, so corrupt, encrypted, or unreadable documents may still fail during analysis.

Completions, uploads, and deletions record metered usage. Model discovery and file metadata reads have no separate credit charge. Document extraction and image analysis are charged through the completion request.

Use usage.charged_credits to read the charge for an operation. One credit equals 1,000,000 microcredits. Key credit limits are separate from account credits; either can prevent a request. Review key usage and configure credit limits in Settings → API Keys.

Model context and visual limits still apply even if each message and attachment is within the API limits. Key budget reset periods are rolling daily, weekly, or monthly periods, beginning when the key is created or its previous period rolls over.

A request that starts with available budget can finish slightly above a small remaining key balance, because its final cost is known after generation. New completions and file mutations stop once the limit is reached. Reservations prevent concurrent requests from spending the same available key budget.

Send an Idempotency-Key for each completion, upload, completion of an upload, and deletion. It is optional, but strongly recommended to avoid repeating work and charges after a connection failure.

Idempotency-Key: a-unique-key-for-this-operation

• Generate a unique key for each new operation. Save it alongside the original request.
• Retry that operation with the same API key, idempotency key, and unchanged inputs. Once settled, its stored status and response can be replayed for 24 hours without another provider call or charge.
• A replay includes X-Idempotent-Replayed: true. Reusing a key with different inputs, or while the first request is in progress, returns 409.
• Cached outcomes can include errors. Repeating the same key may return the same failure rather than execute again. Check the outcome before starting a new operation.
• After the replay window expires, reusing a key starts a new request and may incur another charge.

Use exponential backoff for temporary network, rate-limit, or service failures. Retain the same idempotency key while resolving an uncertain request. Do not retry invalid input, expired credentials, or exhausted credits until you fix the cause.

Deleting a file does not erase an existing cached completion or upload response within its replay window. An upload replay after deletion returns its original response and does not recreate the file.

Errors use a stable JSON structure. Inspect error.code for handling, and retain request_id or the X-Request-Id header when contacting support.

{
  "error": {
    "type": "request_error",
    "code": "invalid_request",
    "message": "messages must contain 1 to 20 alternating user/assistant messages, end with a user message, and stay within 64,000 characters."
  },
  "request_id": "request-uuid"
}