The Oddlynew Documents API

The Documents API creates and reads an organization's documents over plain HTTPS: https://api.oddlynew.com. A script, a migration or your own server puts material into Oddlynew and reads it back, without a person in the loop. Serving published pages to a website is the Content API; this page is about the documents themselves.

The machine-readable contract lives at https://api.oddlynew.com/v1/openapi.json. This page explains the model; the OpenAPI document is authoritative for exact shapes.

One promise governs the create: your document is saved when the response returns. Search catches up in the background, usually within minutes; large imports take longer, and the response tells you where the document stands.

Keys

Every request carries a key as a bearer token. Which key you use decides what the request may do:

A Submitter carries no other permission, so an importer that also reads its documents back uses a second key. A Submitter may only name one of the organization's own types it was given, in any revision of that type; any other typeId, or none, answers 404 type_not_found, the same answer as a type that does not exist. A personal key acts as you: it does only what your role allows, in the organizations you chose for it.

An organization the key may not act in answers 403 with error: "insufficient_scope", and a missing or unusable key answers 401 with error: "invalid_token". Keys are secrets: keep them server-side, never in a browser bundle.

Create a document

POST /v1/orgs/{orgId}/documents with a JSON body:

A new document answers 201:

The response may also carry warnings (the body was saved, but something in it probably did not survive a conversion, such as literal escape sequences) and sizeAdvisory (the document is longer than its type suggests). Both are hints; the create succeeded.

Retrying safely

The create takes no Idempotency-Key header. creationId is its replay key. After a timeout, a dropped connection or any answer you could not read, send the same request again with the same creationId: the existing document comes back with 200 and created: false, and nothing is created twice.

A replay returns the document as it stands; it never applies a changed body. The same creationId with a different title, type, metadata or language answers 409 creation_id_conflict with the documentId and the fields in mismatches. Without title, the title is worked out from the body on every attempt, so a retry whose first heading changed is such a conflict too. A creationId used where this key cannot replay it answers 409 creation_id_unavailable. Mint one creationId per source item and store it beside the source, so a second run over the same source creates nothing new.

Where the document stands

index on the receipt says how far the document is on its way into search:

Whatever the state, the document is saved at currentVersion and can be read at once. Import first and check afterwards: list by indexState rather than polling each document.

Read documents

The list needs typeId and pages with cursor and limit (1 to 50). It matches every revision of the type unless typeMatch=exact narrows it to the one named, and indexState narrows it to one of the states above. A list is served through caches and can miss a change of the last few minutes; a single document is always read fresh.

A single document comes back with its metadata and its body as typed blocks, not as Markdoc. It is the last saved version: an edit still open in an editor shows once it is saved. include=index adds the index state.

Every read carries a required caller-owned Idempotency-Key containing a UUIDv7. Mint one fresh value for each logical request, and reuse that value only when retrying the same request after an ambiguous response. It names the request for your own bookkeeping; the platform never replays an earlier answer under it.

Search documents

It is the search the search tool of the MCP endpoint runs, through the same function, so the rows and their order are the tool's. mode is required: fts searches the search index and can lag a recent write; exact matches the saved text as typed and needs at least three letters or digits in a row, or answers 400 query_too_short; semantic searches by meaning, for passages whose meaning is close to the query even in other words; hybrid runs fts and semantic side by side and merges their results, as the tool does by default. semantic and hybrid lag a recent write as fts does. A semantic search that finds nothing while some of the content it covers is not ready for it yet answers 409 semantic_search_incomplete instead of an empty page, with coverage partial or none; search with fts, exact or hybrid meanwhile. A document kept in several languages comes back once; preferLanguage answers with its copy in that language, and languageCopies=all returns every copy. Each search is metered once per Idempotency-Key, and is never served from a cache.

Editing

An edit works on the live state, not on the saved version. Read the document live first: the answer carries a writeBasis. Send it unchanged with an ordered batch of block edits, the ops of the editDocument tool of the MCP endpoint. The batch applies whole or not at all, and the answer carries the writeBasis for the next edit. Editing needs a key that may change documents: a shared agent key, or a personal key with write.

An edit applies at most once. 409 stale_live_revision means the document changed after your read, possibly by this very edit sent earlier: read it live again and check whether your change is there before you send it again. 422 edit_invalid refuses the batch as written, and detail says what to change. Both routes take the same Idempotency-Key as every read.

The same API also creates document types, reads a document's live state, versions and rescues, edits a document's blocks, and reads Lenses; the OpenAPI document describes those routes. It does not delete documents.

Refusals

Every refusal is JSON with an error code; branch on it, never on the message.

A capacity refusal that carries a retryAt also sends Retry-After; wait that long, then send the same request again. knowledge_capacity_exhausted has three meanings:

Depending on the plan, bulk creates can count against an allowance of new documents for each 30 days. Past it, a bulk create answers 429 bulk_slot_denied with reason: "document_allowance_exhausted" and a retryAt; wait until then or send writeClass: "interactive". A bulk_slot_denied without a reason is a capacity refusal of the bulk lane: with a retryAt, wait for it; with retryAt: null, message, when present, says whether the document is too large for one create or no reliable time is known.

The free organizations of a new account have no bulk lane until the account is verified, so their creates normally run as interactive whatever writeClass says. A bulk create that still reaches the bulk lane there answers bulk_slot_denied with reason: "verification_required": send it with writeClass: "interactive", or verify the account.

Writing a well-behaved importer

The ceilings in front of the API exist for abuse, not for pacing, and may change without notice; write your client against the refusal shape, as the platform's refusal contract describes it.