API conventions
MarkdownThe rules every endpoint shares: requests and responses, request ids, versions, pagination, idempotency, conditional requests, jobs, errors, retries, and rate limits.
Requests and responses
| Item | Rule |
|---|---|
| Address | https://api.mirabase.dev, with every endpoint under /v2 |
| Authentication | Authorization: Bearer <API key>, see Authentication |
| Request body | JSON in UTF-8 with Content-Type: application/json. File content is the exception: raw bytes with the file's own type |
| Field names | Lowercase with underscores, such as next_cursor |
| Times | RFC 3339. Responses are always UTC, such as 2026-11-06T08:30:00.000Z. A time in a request needs an offset |
| id | Opaque strings. Store and send them back as they are. Do not parse them or rely on a prefix |
| Validation | Strict. An unknown field or query parameter returns 422 validation_error with field naming it |
| Errors | Every error has the same shape, see Errors below |
Request ids
Every response carries X-Request-Id, and request_id in an error body is the same value. Include it when you contact support. You can also send your own X-Request-Id and the service keeps it. If the value is invalid, the service replaces it with a new one.
Versions
- The major version is in the path:
/v2. - Every response carries
Mirabase-Contract-Version, now1.0. A request does not need this header. A value the service does not support returns 400unsupported_contract_version: drop the header. - New endpoints, optional parameters, and response fields arrive without a new version, so a client should ignore response fields it does not know.
- Endpoints marked Coming soon do not exist yet and may change before launch. Endpoints marked Deployment option are optional. Both are labeled in the API reference.
- The machine-readable contract is the OpenAPI document. Its address and the spec version for these docs are in the API overview.
Behavior changes
The latest update changed the existing behavior listed here. New parameters and fields are not listed: see the guides and the API reference.
POST /v2/retrieval/answerno longer uses thechangesandskillssources when you send noweights. A question with no related evidence returnsabstainedwithreasonno_evidence. To get the earlier behavior, sendweights. See Answers with citations.- Answers running at once per principal went from 1 to 3.
- The error envelope of a 429
rate_limitedgainedlimit. A 429 for a concurrency limit no longer carries theRateLimit-*headers. See Rate limits and quotas. POST /v2/memorieswith aprojectoragentmemory that matches a current one returns 200 with the existing memory, instead of creating another and returning 201.- Reading
view=tablebefore processing finishes now returns 404content_not_readyinstead of 404not_found. tools/listover MCP has 8 more tools, and a key with a metadata scope sees only the tools it can call. See Connect an Agent (MCP).- When an MCP tool call succeeds, the service places the result JSON in the
contenttext. Only when the negotiated protocol version is2025-06-18or later do the nine read-only tools also include the same object instructuredContent. See Protocol versions. When a key lacks the capability required by a tool, it receives a tool result withisError: trueand the codeforbidden, rather than the JSON-RPC error-32003. - A failed MCP tool result no longer carries
structuredContent, at any protocol version: thecontenttext describes the error, and_meta["dev.mirabase/error"]carries the envelope. See Tools. GET /v2/openapi.yamldescribes only the operations an API key can call, with examples. Console, operator, and not-yet-live operations are no longer in it, and itsETagchanges accordingly.stated_dateno longer comes from a date mentioned in the middle of a sentence: only from a date marked with words such as "as of", the date in a section heading, a date that starts a line or a clause, and the date at the head of the document. See Search.- The service computes a table aggregate only when it understands the whole question, and never on an older version of the table. Some questions that previously returned a computed result now return
table_aggregate:not_computed:<reason>. See Context. - For questions about the current state, newest-first ordering now applies only to evidence about the same subject: the same Entry, the same web page saved more than once, or Entries that share a
metadata.subject_keyvalue. Similar paths or titles, or being in the same folder, do not count. Evidence on a different subject with a similar score is no longer ranked higher solely because it has a newer date. See Answers with citations. - MCP
initializenow responds with the protocol version requested by the client (four versions from2024-11-05to2025-11-25are supported) instead of always returning2024-11-05, and the server name is nowmirabase-developer. See Protocol versions. - When the deployment does not distill memories or the Entry has
memory_exclude, a conversation'smemory.stateisskippedfrom the start, with the reason specified inreason, instead of starting aspending. See Why distillation is skipped. - A version that was already distilled stays
readyafter the deployment turns distillation off or removes the model, instead of turningskipped.distill_disabled,model_not_configured, anddistill_pausedare shown only to an unrestricted key of atenant_adminor one withknowledge:manage; other keys seedistill_unavailablein place of the first two, and no reason in place ofdistill_paused: the state stayspending. See Why distillation is skipped. - In an account with a team, an Admin can no longer issue keys for Agents or end users created by others, or revoke the keys of the Owner or another Admin. See Creating a key through the API.
- When a write returns 429
ingest_backlog,Retry-Afteris 30 to 600 seconds instead of a fixed 30. WhenRetry-Afteris longer thanmaxRetryAfterMs(max_retry_afterin Python, 60 seconds by default), the SDKs do not retry and throwMirabaseRateLimitError. See When the processing queue is full. - The SDKs check the API key when the client is created: white space at its ends is dropped, and a line break, space, control character, or non-ASCII character inside it throws
MirabaseConfigErrorwith codeinvalid_api_key, instead of failing when a request is sent. See Handle errors. - With
redact_secretson a conversation, each message is now redacted on its own and the title separately;secrets_redactedis the number of replacements actually made in the messages and the title. A credential split across two messages is no longer matched as one. Text ingest is unchanged. - The
scoreand order of retrieval results, and the candidate counts inexplain, are computed only over content the caller can read. A caller with a limited read range (for example, a member with aread_root) may see differentscorevalues; a caller who could read every candidate gets the same results as before. GET /v2/retrieval/traces/{trace_id}no longer returnssummary.candidatesandsummary.fused_countfor traces recorded before this update.- While an account is pending approval, a console session can only manage API keys and view the account and the read-only lists. Retrieval, reprocessing, deletion, and creating or changing a Space return 403
account_pending_approval;POST /v2/spacesreturned 201 before. See Create a key in the console. - A model call that was never sent (it failed while connecting) no longer counts toward the monthly model quota. When a model call is refused for quota, the
messageof the 429quota_exceededno longer states how much the call needs or how much of the account's quota remains: readGET /v2/usage. - Within one account, memory distillation for different Spaces takes turns, so a backlog in one Space no longer delays distillation in another; ingesting conversations no longer delays the distillation of text.
Pagination
Lists return {data, next_cursor}. Pass next_cursor back as cursor for the next page. The last page has no next_cursor. Cursors are opaque, so do not parse or build them.
| Parameter | Meaning |
|---|---|
limit | Items per page: 20 by default, 100 at most |
cursor | The next_cursor of the page before. Keep the other parameters the same while paging |
# First page
curl "https://api.mirabase.dev/v2/entries?limit=100" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
# Next page: pass next_cursor back as cursor.
curl "https://api.mirabase.dev/v2/entries?limit=100&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Each list states its order in its own entry of the API reference. The change feed is the exception: it returns {data, cursor, has_more}, and cursor is always present so you can continue from it, see Sync. Search is not paginated: limit sets how many hits it returns.
Idempotency
When the network drops you cannot tell whether a write happened. Sending it again with Idempotency-Key is safe: the same key, principal, API key, operation, and input return the first result for 24 hours without running again.
| Item | Rule |
|---|---|
| Format | 1 to 512 visible ASCII characters. A UUID is a good choice. Use a new key for each logical request |
| Kept for | 24 hours |
| Same key, different input | Returns 409 conflict with remediation.action use_new_idempotency_key |
| Scope | Per API key: two keys using the same value do not affect each other |
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/ingest" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Idempotency-Key: 7d3f4c0e-5b1a-4f6e-9c2d-1a2b3c4d5e6f" \
-H "Content-Type: application/json" \
-d '{"kind":"text","text":"The launch moved to March 14."}'- Most
POST,PUT, andPATCHendpoints take the header, and merging a branch requires it. Each endpoint's parameter table in the API reference says whether it does. - Endpoints that do not take it are safe to repeat as they are:
GETchanges nothing, the uploadparts,complete, andabortcalls are deduplicated by the upload id, and repeatingPATCH /v2/entries/{entry_id}gives the same result. - A single
DELETEdoes not take it: the second call returns 404not_found, so you still know the outcome. To make a delete replayable, send it throughfiles/batchwith a key. - The SDKs generate a key for every call that takes one, and a retry reuses it.
Conditional requests
A file's ETag is the id of its latest version. Versions never change, so it is a strong validator. Use it to avoid overwriting someone else's change, and to avoid downloading what you already have.
| Header | Used on | Effect |
|---|---|---|
If-Match: "<etag>" | Writes, edits, deletes, reverts | Runs only if the file is still at this version. Otherwise it returns 412 precondition_failed, and current_version_id in the error is the version now |
If-None-Match: * | Writes | Writes only if nothing is at the path. An existing file returns 412 precondition_failed |
If-None-Match: "<etag>" | Reads | Returns 304 with no body when the content has not changed |
Range, If-Range | Reading the original | Returns 206 with the bytes asked for. A range outside the file returns 416 range_not_satisfiable |
A successful write returns the new version's ETag, so the next If-Match can use it without another read. See Files for a full example.
Jobs
Work that cannot finish within the request becomes a job: it returns 202 with a job_id and a Location that points at the job. Poll GET /v2/jobs/{job_id} every second or two until the status is final.
What each status means is in DevJobStatus, and the kinds of job in DevJobKind.
| Request | Notes |
|---|---|
| Processing after a write (parsing, indexing, distilling) | The write itself is committed and processing runs in the background. Prefer: wait=N, at most 10 seconds, holds the response until processing finishes, see Files |
| Large tree operations and branch merges | Send Prefer: respond-async when the request is over the synchronous limit, see Files and Branches |
| Exports and imports | Always jobs, see Sync |
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Only whoever started a tree, merge, export, or import job and the Space owner can read it. The service keeps these jobs for 7 days after they finish. Jobs have no long poll.
Errors
Every error has the same structure. type is the broad class, for handling a whole class of errors the same way. Branch on code and remediation.action for the specific case: they are stable. message is for people and may change.
{
"error": {
"code": "precondition_failed",
"type": "conflict",
"status": 412,
"message": "the file has moved on",
"request_id": "req_a18f",
"retryable": false,
"current_version_id": "ver_3c44",
"remediation": {
"action": "reread_and_retry",
"doc_url": "https://api.mirabase.dev/llms.txt"
}
}
}For the meaning of each field, see DevErrorBody. For how type follows the HTTP status, see DevErrorType. Every error code is listed in Error codes.
Every invalid field at once
When a request body fails validation, errors on the 422 validation_error response lists every problem found, so one round of fixes is enough. Paths are dotted, such as messages.0.role.
{
"error": {
"code": "validation_error",
"type": "invalid_request",
"status": 422,
"message": "query is required",
"request_id": "req_b27c",
"retryable": false,
"field": "query",
"errors": [
{
"field": "query",
"code": "validation_error",
"message": "query is required"
},
{
"field": "colour",
"code": "validation_error",
"message": "unknown field: colour"
}
],
"remediation": {
"action": "fix_request",
"doc_url": "https://api.mirabase.dev/llms.txt"
}
}
}The SDKs throw a subclass of MirabaseError chosen by HTTP status, such as MirabaseNotFoundError or MirabaseRateLimitError, and the error object carries type and errors too. See SDK.
Retries
- Check
retryable. Wait forRetry-Afterwhen it is present, otherwise use exponential backoff with jitter. - Send
Idempotency-Keywhen retrying a write, or you may create an extra version.
The seconds Retry-After gives for each code are in Error codes.
Rate limits and quotas
Authenticated responses carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Each key has two buckets: one for GET and HEAD, one for everything else. The bucket holds one minute's allowance, so a burst can use it all at once. An account also has a total across all its keys, and a request refused by the total reports that bucket in these headers. Limits are enforced per server process, so treat the numbers as a guide, not an exact allowance.
curl https://api.mirabase.dev/v2/limits \
-H "Authorization: Bearer $MIRABASE_API_KEY"
curl https://api.mirabase.dev/v2/usage \
-H "Authorization: Bearer $MIRABASE_API_KEY"Every limit's name, default, scope, and what exceeding it returns are in the API reference. The defaults are provisional: GET /v2/limits reports what this deployment enforces, and GET /v2/usage shows what you have used. When a concurrency limit is full, a request first waits on the server for a slot, so the server slows a short burst of parallel requests rather than refusing it.
The error envelope of a 429 rate_limited carries limit, which says which limit was hit. request_rate is the per-minute request allowance: wait for Retry-After, then retry. concurrency is a limit on calls in flight: the request already waited on the server for a slot, and the response has no RateLimit-* headers. Run fewer calls at once; waiting longer helps less.
The limits of a single endpoint, such as file size, batch size, and value ranges, are in that endpoint's description and parameters in the API reference.
Plans
Every account has a plan, returned in plan by GET /v2/limits and GET /v2/usage. The plan determines which limits apply; GET /v2/limits returns the specific values.
| Plan | Description |
|---|---|
standard | Uses this deployment's limits. |
free | The initial plan for self-serve accounts. In addition to this deployment's limits, it caps storage, monthly writes, monthly model tokens, monthly model spend, and the request rate. When a stored quota is used up, the API returns 429 quota_exceeded, with quota identifying the quota. |
legacy | An account opened before plans existed. Like standard, it uses this deployment's limits. |
Next steps
- Error codes: what each error code means, with its
remediation.action. - SDK: the clients already implement these rules.
- API reference: the parameters and responses of every endpoint.
