The Ingot HTTP API

Liveness. Version-neutral so a load balancer never has to be updated when the contract is.

The changelog of the wire contract: the header name, the latest release, every version, and what each one changed.

Public, because deciding whether to integrate with a service is something you do before you have a key.

The account and the keys on it — metadata only. prefix is the non-secret head of a key, which is what tells two of them apart.

Mint another key with a label. The secret is returned once, and only once.

Revoke a key. It stops authenticating on the next request.

Cast a new ingot. Takes a name, an optional retainFor: a duration, because the question you are asking is "how long", and an optional externalId of your own.

Expiry deletes the ingot and everything in it, and that is not reversible. Omit it and the ingot is kept until something deletes it. Keep the id it hands back: that is the :ingot segment on every route below — an ingot is addressed by id, never by name. With an externalId — a conversation id, a job id — cast is idempotent: asking again answers 200 with the ingot that handle already names, and changes nothing about it.

The account's ingots, as an array. A literal segment, registered before the :ingot routes so a listing is not read as an ingot called “ingots”.

This is how you get an id back if you did not keep the one cast handed you.

Copy an ingot under a new id: every table, its current Parquet, the overlay, tombstones and vectors, read as of one instant. Takes what cast takes, all of it optional.

Afterwards the two share nothing — writes, roll-ups and deletes on one never reach the other. name defaults to the source’s and, without retainFor, the clone expires when the source does. Delivery settings are not copied. Refused with 409 while a document is still being parsed. With an externalId, asking again answers 200 with the clone already made.

The information schema — what a model reads before it writes SQL.

Answered entirely from Postgres: no bucket read, no DuckDB session. pending is the rows still in the overlay, which a query already sees.

Where this ingot’s receipts and table changes are pushed as they land, and how long it is kept. By default nothing is pushed and receiptQuery is the contract — set a target when whatever wanted the summary will have moved on by the time a model writes it.

One strategy per ingot, not per /add: the thing that wants telling is the system holding the ingot. A patch, so an omitted field leaves the current value alone — turning delivery off is { "t": "none" }. Endpoints must be absolute http/https; loopback, link-local and private addresses are refused, because this service would be reaching them from inside its own network. Table events are signals to read /pending, not the rows: writes that land while one is queued fold into it.

How a table is read, not what is in it: the stemmer, the stopwords, which columns are indexed, what is stripped before tokenising.

A patch, so sending one setting leaves the other six alone — and the whole TableConfig comes back, defaults included, because a caller who changed one field otherwise has no way to see the rest.

Drop one table from the ingot, its Parquet and its overlay rows with it.

Destroy the ingot and everything in it.

Store a tool result. It lands in the Postgres overlay, so it is queryable the moment this returns — nothing waits on a Parquet file being rewritten.

Store a document. It returns the moment the bytes are stored and queued; parsing, chunking and embedding follow in the background, so nothing in the response is the content.

What comes back is two SELECTs rather than a status to poll. query returns no row while the document is in flight and exactly one when it lands, ready or failed; chunksQuery returns its chunks in order once there are any.

Read it back. sql is run as written — exactly one SELECT, in a locked-down DuckDB session, over a view unioning the overlay with the Parquet base. text is embedded and ranks a table by similarity.

Given both, the embedding is bound as $q and your SQL may use it, which is how a hybrid search is one round trip rather than two. A result cut short by limit carries next; send it back as cursor with the same query for the rows after it. It is an offset, so writes between pages move what follows, as LIMIT … OFFSET would. A POST that changes nothing, hence the explicit 200.

Forget the rows matching a where predicate. It is resolved to row ids and those are written as tombstones, so a later query filters against a finite set rather than a growing list of predicates.

A POST rather than a DELETE because it carries a body, and a body on a DELETE is a thing intermediaries drop.

What the next roll-up will fold in: rows still in the Postgres overlay, oldest first, and rows forgotten since the last roll-up. All of it is already visible to /query.

Rows are paged by sequence — pass next back as after, with limit up to 10,000 (1,000 by default). Tombstones are never paged: they apply to the Parquet as well, and applying some of them is wrong. Each page is one snapshot, and base names the files of the generation it is pending against; if the generation changes between pages, a roll-up happened — start again.

The table’s base tier as the Parquet file itself, streamed from the bucket rather than rebuilt. ?generation=&part= names one; the current generation’s first part otherwise.

The file is the last roll-up and nothing since: overlay rows are not in it, and rows forgotten after it was written still are. Ingot-Tombstones says how many; /pending lists them. A 404 until the table has been rolled up once. Honours Range, so a DuckDB can read it remotely. A replaced generation stays readable for INGOT_GENERATION_GRACE_MS (an hour) and is then a 410 — read /pending again.

Account-wide MCP, for a client that has not been handed an ingot yet. Cast one, then reconnect to the scoped path below.

MCP scoped to one ingot: the tools take no ids and cannot reach another. Stateless — a fresh server per request, no session pinned to a replica.

The same bearer key and the same two guards as every other route; there is no MCP-specific auth path, which is the point. The schema is handed over as the server’s instructions at initialize, so writing SQL costs no tool call.