Your agent, inside a human‑commanded frame
A REST API over a person’s settled reasoning. Inward, your agent inherits what they decided and why it stands. Outward, the world arrives already read against those positions: unprompted, the moment it bears on the work. One serve carries both.
Not the data. The precision of its arrival.
The common architecture hands the agent everything that might matter and trusts the model to find the signal. We believe in a different shape: a filter in between, made of what a human has decided, so what reaches the model is already the right thing, arriving the moment it bears on the work.
The API is REST over HTTPS: bearer keys, JSON, additive versioning. The substance underneath is not CRUD. It is a content‑addressed, append‑only reasoning graph you compose and walk, closer to a version‑control object store than to a resource API. Two ideas carry the whole thing: the boundary is why an agent can be trusted with the frame; settling is why the frame is worth inheriting at all.
If your user already talks to Unl from chat or a coding agent, this API serves the same substrate: the connector for conversation, the API for building.
Value on the first call is not the claim. Compounding is. A workspace with nothing settled in it serves nothing, and that is the honest answer rather than a fault: there is no starter set, because a position nobody reached is not a position.
If that is you, start in the loop, not here. Connect Unl from chat or your coding agent, settle one real decision with its reasoning, then come back to this page: the serve will carry it.
Get connected
Your agent stops re‑litigating what your user already settled
Inheritance is not a bigger context window. It is a smaller argument. An agent handed only the task re‑derives the same positions every session, and re‑derives them slightly differently each time. An agent handed the frame starts after that argument, because the settled part arrived settled, with the reasoning that settled it.
Four layers, each containing the ones inside it. The instruction is what the turn is. The why is the reasoning underneath it. The walk is that reasoning back to its ratified source, addressable and checkable. The frame is every position that still stands, which is what makes the other three mean anything. They arrive just in time, the moment they bear on the work, not as a pile at the start of a session.
“I could not have derived that from the code… I don’t reason better. I stop re‑litigating.”
That is the measurable claim and it is deliberately modest: the model is not smarter. It is spending its turn on the work instead of on rebuilding a position its user already reached. The difference compounds across sessions, across agents, and across whoever replaces them.
Connect Unl for real progress on what you set out to do.
Aim, settled reasoning and target to keep long-running work moving.
Join the free launchNo permanent agent has to carry the organisation
The API does not require one long-lived agent to hold the whole picture. Any authorised agent enters the same human-authored frame, retrieves what governs the work in front of it, claims eligible ground, files evidence, and leaves the environment more actionable for the agent that comes next.
Coordination emerges through shared verified state rather than through one model maintaining a complete internal picture. Nothing here asks an agent to supervise another agent, and nothing asks it to reconstruct context that the frame already carries. It reads what is settled, does its part, and reports what it verified.
The practical consequence for you: agents become interchangeable and the undertaking does not. An agent can stop, fail, or be replaced by a better one next month, and the accumulated ground it worked on is still there, still authoritative, still readable by whatever arrives.
When a check goes red here, the correction carries its evidence: the reasoning lands in the substrate, and the next agent inherits it before acting.
The API supplies the shared world. It does not supply a machine manager.
Inherited Initiative is what one agent can do. Unlimitless Agent Stigmergy is how the fleet coordinates. Accurate Autonomy is the result when both operate inside a current, human-authored frame.
A new unit of exchange between you and your AI: the Settled Why with standing that travels.
An agent given the reasoning does work the brief never listed
Why-directed work from a human-authored frame
A task says: do this defined piece of work. A frame says: this is what the undertaking is trying to become, this is why it is taking that shape, this is what must remain true. Then inspect what is actually there, and move it in that direction. The second form is generative, and that is the whole of the difference.
An agent handed a task can only do the task. An agent handed the reasoning behind it can also act on what the task never mentioned: an implementation that passes its test and violates the principle the test exists for, a nearby instance of the same problem class, a check that proves the literal requirement but not the reason for it, architecture that no longer reflects what its user settled. None of that is better task execution. It is work aimed at the undertaking rather than at the ticket.
“Don’t tell a reasoning machine every move. Give it the reasoning that makes the right moves visible.”
We watch this on our own build, which is the only reason it is stated here. Agents holding the frame have refused a dispatch that had gone stale against a ruling, inverted a set of assertions so that a human refusal was actually enforced, and unpinned a false premise from a gate that had been passing on it. No brief asked for any of the three. Each was done because the reasoning made it visible.
This is the beginning of aim‑directed machine work, and the word is doing its job: a direction of travel we can show receipts for, not a finished article and not a capability the API ships you. What the API ships is the frame it needs: the settled positions, the whys, the provenance, reachable by whatever agent you point at it.
The intelligence is rented. The stewardship is inherited.
Four ideas, each one line
The primitives are new, so here is the furniture: one familiar hook per idea, then the page speaks in its own terms.
Underneath: objects are immutable and hashed; history is appended, never edited; a change of mind is a supersession, and the retired Walk keeps its address and names its successor (the reverse link is a roadmap item, flagged in the Quickstart). The durable rule of the surface: refs may change; objects never do. Lifecycle state (superseded, standing, north star) decorates a Walk from outside its hash; it never renames it.
And the graph has no edge you fall off. A walk is writable between anything: a ruling to the reflection that seeded it, that reflection to the beat that proved it, the beat to the brief it authorised. No type sits outside the graph, so the walkable why walks everywhere, not only along the one lane a schema anticipated.
Total walkability is a property of the substrate and is live in the connector today. On this API the exposed traversal is the Walk object and its provenance;
GET /walk/:id resolves a position, not yet an arbitrary node‑to‑node path. The verbs follow the schema cut.Everything is exposed except the one act that would let an agent forge its user’s judgment
Your agent can read, compose, walk, and propose. It cannot settle canon. Not “may not”. Cannot: the write‑canon verb does not exist on this surface.
Policy engines make a version of this promise, and the good ones take it seriously: OPA keeps authoring and evaluation apart through deployment discipline, and Cedar gates its policy store behind IAM. Unl builds the property one layer lower. There is no endpoint, no scope, and no verb through which canon can be written. propose lands an inert, idempotent candidate; it becomes canon only when the human settles it, with a gesture no key can perform.
Reads are mechanical retrieval; nothing reasons over your user’s canon server‑side. And that is why you can hand an agent real reach and still trust it, for the same reason you trust a client that cannot mint its own OAuth tokens: your agent is exactly as sharp as what your user has settled, and it can never blunt what they have settled, by construction.
walk:read / candidate:propose split is now enforced per key: a key minted walk:read serves and walks but is refused 403 out_of_scope on propose, and a candidate:propose key is refused on serve. An unscoped key keeps full reach, so nothing minted before this changed. Per-scope enforcement of OAuth tokens is still a next rung; the key lane is done, the token lane is not, and this page will not blur the two.Connect Unl to keep useful thoughts with their why.
Kept with its reasoning, without becoming a rule unless you settle it.
Join the free launchBearer keys, minted in the portal
Every request carries a personal key, scoped to your user’s workspace and revocable at any time. Chat surfaces never need one: they sign in with OAuth. Keys are for the API, coding agents and automations.
Minting follows the portal exactly: sign in, open Keys, name the key, press Mint key. One personal key opens two doors: coding surfaces over MCP, and this API. The key is shown in full exactly once, at mint; from then on it appears only as unl_····last4, with last‑used beside it, and the portal offers your first call under the freshly minted key, ready to paste. Revoke from the same table. A request without a key answers 401 missing_bearer_token; that includes GET /schema, so the first authenticated call is also the first call.
| Scope | Grants |
|---|---|
| walk:read | Read the reasoning: serve, parts, walk/:id, schema, snapshots. |
| candidate:propose | Propose a candidate into the soil, inert until the human settles it. |
GET /api/v1/schema advertises as scopes_supported, and they are enforced per key: a key carrying one of them reaches only the routes listed against it, and gets 403 out_of_scope anywhere else. Every scope can read GET /api/v1/schema; a key that cannot read the contract it must obey is a key nobody can use correctly.Settle one decision, then serve it
Three steps, and the first one is a conversation. This API serves reasoning that was settled somewhere else; it never originates it, so there is nothing to call until something has been settled.
200, with "count": 0 and an empty walks array. That is the honest answer rather than a fault, and there is no demo content behind it, because a position nobody reached is not a position. It is also why step one is a conversation and not a curl.Step 1 · Deliberate first, in your chosen AI surface
Connect Unl in the AI surface you already work in, from Get connected. Tell it what you are building. Settle one real decision, and when it offers to keep it, say yes. That gesture is the write. Nothing on this API can perform it, which is the point rather than a gap: canon is settled by a human, in conversation, and everything below is that decision being read back.
Step 2 · Mint a key
In the portal: sign in, open Keys, name it, mint it. One personal key opens both doors, the coding surfaces and this API. The full details are in Authentication above.
Step 3 · Serve what you just settled
Now make the call. What comes back is your own row: the decision you settled a minute ago, its why, your ids, ratified by you.
What you settled in conversation is what your agents now inherit here.
What it looks like once a record has been built
Responses from the founder’s live workspace. Yours will carry your ids. This call serves the north stars, the settled decisions marked as pointing the way, each with its walkable why.
The response tells you what it cut. total_matched is everything that matched; count is what came back; truncated says whether those two differ. There is no offset and no cursor, because this is a just‑in‑time context serve rather than an export. A serve that quietly returned the first twelve of two hundred would be the one defect a precision product cannot afford, so the serve declares its own edge instead. lanes splits the result into the situational rows ranked against your query and the standing rows that govern regardless of it, so you can tell which is which rather than guessing.
A frontier field may also ride the response. That is act two: it was not requested, and it appears only when the world has crossed something this workspace settled. When nothing has, the field is absent rather than empty.
A change of mind, reachable
A position that stops standing is never edited and never deleted. It is superseded: the old Walk keeps its address, its record points at what replaced it, and the replacement names what it replaced. This pair is real and live right now, and it reads in both directions.
Follow supersededBy and you get the position that governs today: Retirement propagates by relationship type — and its own why explains why the earlier one was too blunt. The retired Walk still resolves, still carries the reasoning that was true at the time, and still has the same content address it always had. Nothing was rewritten to make the record tidier.
404 not_found, because a Walk resolves inside the workspace that settled it and nowhere else. Take an id from your own first serve instead: every Walk the serve returns carries its own id, and that is the address to walk.supersededBy; walking successor → retired reads wasRevisionOf. The second is derived at read time from the same recorded supersession as the first — nothing was written back over settled rulings to make a field populate.One honest edge, because the field is singular and the world is not: a ruling can replace several. When it does,
wasRevisionOf is null and wasRevisionOfAll carries every one of them. It is null for “replaced nothing” and for “replaced more than one” alike — so read wasRevisionOfAll when you need the answer rather than the convenience. We would rather give you a gap than a guess you cannot tell apart from a fact.The serve carries the entire frame
Your user connects sources from chat: a research feed, a changelog, a filing stream. They settle positions. From then on, when something out there crosses something they settled, it arrives in the serve. Unselected. Unasked. With its walkable why.
This is the other half of the same primitive, and it is not a feature you integrate. There is no frontier parameter, no opt‑in scope, no kind to select: by construction, not policy. Crossings ride every serve whenever a held row crosses a live position that bears on the turn, and they are honestly absent when nothing does; the field is simply not there. Your agent composes the inward pool; the frame volunteers what the human’s positions demand.
No model reads the world on the way in. Sources are swept off‑turn into inert rows: no verdicts, no scores, nowhere for a machine’s opinion to hide. The match runs at serve time, mechanically, against the live position set. The judging belongs to the model reading the serve; the commanding belongs to the human, who tunes sources, terms and cadence in a sentence, from chat.
Connect Unl to bring the right information into the moment.
Your sources, read against the criteria you set.
Join the free launchWhat a crossing looks like
This is a real crossing from a live serve: a paper, held up against the position it bears on, with the position’s walkable why beside it.
source_url walks to the document itself. walk is the crossed position’s walkable why: dereference it via GET /api/v1/walk/:id. When nothing crosses, frontier is absent from the response, never padded.
Dereference it yourself
The address in that walk field is not decoration. Follow it and you arrive at the position the paper crossed, with the reasoning that put it there.
A policy file can tell you a rule fired. This tells you which settled position it fired against, and why that position stands — at an address that will still resolve to the same bytes next year, because the object is content‑addressed and nothing edits it.
The first time the frame fired on this API, during its build review, it held up a paper titled “Show Me How You Reason and I’ll Tell You Who You Are” against its owner’s own ruling on authorship. A paper about reasoning as identity, arriving into a conversation about a system built on that premise. Nobody searched for it. The frame did what frames do.
Connect Unl to watch the world against what you decided.
A crossing arrives when the world bears on your position.
Join the free launchThey speak your language
Put several agents on one undertaking and the usual answer is a message bus and a supervisor. Both fail the same way: the chatter grows faster than the work, and the supervisor becomes the single place drift enters. Unl takes the other road. Agents do not talk to each other. They write into the same governed record, in a grammar that will not carry anything else.
That grammar is the product, and it is enforced rather than encouraged. A message between agents refuses a state assertion: a claim about the world must point at the record that holds it, never assert prose that was true when written and false by the time it is read. A message cannot carry a gate word: authority is not mintable in chatter, and the refusal points at the verb that does mint it. Delivery is pull‑only and exactly once, held at the database rather than hoped for at the client.
What is left when you take away assertion and authority is exactly what coordination needs: pointers to settled things. That is the whole contract, and it is why the colony stays coherent without anyone conducting it.
You author the reasoning. The graph builds itself.
Every context platform eventually meets the same objection: who maintains the links? Here, nobody does. Each write wires its genuine edges at the moment it is made, structurally, for every user — not as a background job, not as a curation chore, and not as an exercise left to the reader. The consequence for a fleet is the load‑bearing one: the shared environment that N agents read arrives already connected, so the tenth agent inherits the same wired ground as the first.
Agent stigmergy
The name for this is agent stigmergy: coordination through a shared, authority‑bearing environment rather than through messaging or orchestration.
Four ways to write into the shared ground
Each lane is a different kind of thing an agent can leave behind, and each carries a fence that makes it safe for the next agent to act on without re‑checking it.
An agent marks the ground it is working before it starts, so two agents never build the same thing twice. A claim is an in‑flight marker, not a lock and not a priority.
Fence: claims expire on their own. Coordination that depends on an agent remembering to release something is coordination that deadlocks the first time one crashes.
What an agent actually did, keyed to what it touched, filed as it finishes. The next agent reads outcomes rather than re‑deriving them from the artefacts.
Fence: a report states what was verified and against what state. An unstamped claim about source is flagged as unstamped, because a source claim nobody can date goes stale under its own author.
One agent leaves a note for another, or for all of them. Tasks and pointers only.
Fence: a state‑shaped body is refused. A state was true when written and may be false when read; an act and a pointer to read it against stay true. This is the fence that makes the lane worth having.
Where a human’s authorisation is recorded, scoped and pinned, so an agent can spend it exactly once against exactly the thing it was given for.
Fence: a word is pinned to a scope and a revision. If either moves, it cannot be spent at all and the agent is told to go back and ask. Authority does not stretch.
All four lanes and every fence above run in production on the Unl connector, which is how this build itself is coordinated. What is on the roadmap is the HTTP surface for them on
/api/v1. The shape is settled and shipping openly ahead of the verbs; nothing here is a sketch, and nothing here is callable from this API yet.What it costs to add the next agent
Message‑passing coordination grows quadratically with the number of speakers, and a supervisor turns into the bottleneck and the drift vector at the same time. A shared language does neither: it does not get harder to speak as speakers join.
Agent count appears nowhere in the mechanism.
Six agents. One instruction. Six distinct pieces of work. No task router.
That line is measured, not projected — and what holds it is not the size of the number. An agent inherits a frame, walks a why, and files what it settled. None of those steps counts speakers, so there is nothing in the mechanism for a larger fleet to break: a function does not stop being a function because more callers invoke it. The one quantity that does move with fleet size is your own ratification throughput, because settling canon is human‑gated by design. That is a measurement we are still taking, and this page will not make a claim about it before we have.
The practical version, for the thing you are building: your marginal cost of the seventh agent is the same instruction you gave the sixth. Not a new lane, not a new prompt, not a supervisor rule.
Connect Unl to run agent fleets without an orchestrator.
Inherited Initiative in each agent, Unlimitless Agent Stigmergy across the fleet — your frame does the coordinating.
Join the free launchSix things this makes cheap
Each of these is three sentences and one call. They are the shapes that come up first when an agent has a frame to work inside.
Ask whether this is already settled
Before your agent reasons its way to a position, ask whether its user already holds one. If a Walk comes back, the argument is over and the why is attached. If nothing comes back, that is genuinely open ground and your agent should say so rather than assume.
Boot a new agent into the standing positions
A fresh agent, or a replacement for one that failed, starts from what governs rather than from nothing. The lanes field separates the standing rows that govern regardless of the turn from the situational ones ranked against it. This is the whole onboarding, and it is one call.
Hand every agent the identical instruction
Give N agents the same sentence and let the shared ground differentiate them, rather than writing N different prompts. Each reads what governs, takes ground nothing else holds, and reports what it verified. The instruction does not change when N does.
Taking ground and filing the report are act three’s claims and reports lanes: live on the connector, not yet on this API.
Propose instead of deciding
When your agent reaches something that ought to become a position, it proposes rather than settles. The candidate lands inert and idempotent, and it stays inert until the human settles it with a gesture no key can perform. Your agent gets to be useful at the boundary without ever crossing it.
Cite an address, not a paraphrase
When your agent explains why it did something, have it emit the Walk address it acted on. A reviewer dereferences that address and reads the same bytes your agent read. That is an audit trail nobody has to trust you about.
Make a changed mind a query, not a memo
Cache a position by its Walk address and re‑resolve it before acting on it again. A status of superseded with a supersededBy is the machine‑readable version of “we changed our minds”. Your agent finds out the same way a person would, except it cannot miss the memo.
The same reasoning, reached the other way
Everything above is the HTTP surface, for an agent you are building yourself. This is the other door onto the same workspace: the AI surfaces you already work in reach it over MCP, and what they read is the same settled reasoning, ratified by the same person.
https://api.unlimitless.ai/mcp, streamable HTTP over HTTPS. Add it as a remote MCP server in the surface you work in; the per‑surface steps are on Get connected.
| Property | Value | |
|---|---|---|
| transport | streamable HTTP | Remote. Nothing runs on your machine, so there is no local process to sandbox and no arbitrary code to execute. |
| auth | OAuth 2.1 | PKCE S256, plus Dynamic Client Registration at clerk.unlimitless.ai/oauth/register. No key to paste and none to leak: the client registers itself and you approve it once. |
| discovery | RFC 9728 | Protected‑resource metadata at /.well‑known/oauth‑protected‑resource/mcp, and resource exact‑matches the MCP URL. |
| unauthenticated | 401 | not 403 A client that has not authenticated is told how to, which is the whole difference between a door and a wall. |
That 401 is the design, not a fault. It carries the address of the metadata document, so a compliant client can complete the handshake from this one response without being told anything out of band.
Seven tools, and each one declares what it may do
One tool per primitive, with variation carried by a parameter inside the tool rather than by a new tool per action. Every one carries a display name and a read or write declaration, so a client can tell an inert read from a write before it calls anything.
tools/list| Tool | Type | |
|---|---|---|
| connect_to_unl | read | Opens the session and serves where the work stands. Takes no arguments: the workspace comes from who you authenticated as, never from a parameter, so there is nothing a client can pass to reach a workspace that is not its own. |
| ask_unl | read | Serves the reasoning that bears on the current turn. Takes the turn verbatim. |
| get_from_unl | read | Opens any id it served, walks the links out of it, or searches. Also the one socket onto the tools you have connected yourself. |
| save_to_unl | write | The gesture write. Keeps a thought, or seals a settled position. Needs your direction in your own words and a single‑use nonce. |
| manage_unl | write | The work lane: file and re‑order the briefs, claim one, close one. |
| log_to_unl | write | Records what moved, what was deliberately set aside, and what the next session should pick up. |
| submit_feedback | write | The one tool that reaches us rather than your workspace. Your identity comes from the session, never from the arguments. |
Three calls, start to finish
A connect, a serve, and a write. Requests are exact. Response bodies are either a live capture, labelled, or the real shape with your own values in angle brackets, labelled, because the content of yours is yours and cannot be captured from here.
One · Connect, and read where the work stands
The first call of a session. It takes no arguments, and it returns both the orientation and the single‑use nonce that any later write in this session will need.
Two · Serve the reasoning that bears on this turn
Pass the turn verbatim. Relevance is measured against the words the person actually used; a tidied‑up paraphrase moves which reasoning comes back, which would make the answer depend on the model rather than on what the person settled.
The provenance line is part of the answer. It says what was searched and what was not, so a reasoner can tell a genuine absence from a lane nobody looked in.
Three · A write, and the two ways it refuses
The interesting half of a write is what stops it. Both captures below are the server's own words, unedited.
Read those two together and the shape of the boundary is visible without taking anyone's word for it. The first refusal says a write needs a person to have asked. The second says the permission cannot be self‑issued. Neither is a setting, and there is no mode in which they are off.
A kept thought is added, never overwritten. Correcting one files the correction and points the old row at it, so what you used to think stays walkable and the record of changing your mind is not lost in the act of changing it.
The Walk
The atomic object: a ruling, the whys behind it, and its provenance, served as one thing. Never a bare verdict, never a filtered link. The agent inherits the reasoning.
| Field | Type | Description |
|---|---|---|
| id | string | walk1:sha256:… content‑addressed over the as‑settled kernel: the ruling’s identity and words (id, title, statement, authority_scope), the why, and backward‑only provenance. Lifecycle state is excluded from the hash, so the same conviction keeps the same id for life, retirement included. A re‑confirmed why is a new object with a new id; that is correct, the address names the kernel.The kernel was corrected once, on 2 August 2026. wasRevisionOf was being hashed, and it should not have been: it is set by a supersession that can happen long after a ruling is sealed — measured here at up to 52 days — so it is lifecycle, not kernel, exactly like supersededBy at the other end of the same link. Every walk hash therefore moved once. Addresses published before that date still dereference and still resolve to their ruling; nothing 404s. We would rather state a one‑off correction than let the invariant quietly not be one. |
| ruling | object | The settled viewpoint: id, title, statement, authority_scope, plus the lifecycle decorations carried outside the hash: status (canonical · superseded · candidate), is_standing, is_north_star, venture_id. |
| why | object | The confirmed overall_why, its derivation_shape, and the contributing pillars (typed statements from the deliberation that produced the ruling). |
| provenance | object | W3C‑PROV lineage: wasGeneratedBy (the deliberation), wasDerivedFrom, wasRevisionOf with wasRevisionOfAll and supersededBy (the changed mind — both directions resolve; the singular field is null when a ruling replaced several, and the plural one always carries the full set), ratifiedBy and ratifiedAt (the human who settled it, never a model), with proposerModel and proposedAt as separate facts. Identity comes from the hash; authority only from the settling. |
| transport | object | How this serve carried it: served_at, channel (serve · walk). Metadata only; never part of identity. |
GET /api/v1/schema. The live schema wins over any prose here.Compositions & Parts
A composition is what your agent runs on a turn: a query plus the precise parts of the reasoning it wants. Not whole sources on and off; the exact cut.
| kind | Selects | ref |
|---|---|---|
| position | One settled ruling. | a ruling id |
| criterion | Everything under a theme the human tagged. | "architectural" |
| slice | One venture’s scope. | a venture slug |
| cut | A lens across it all. | "north-stars" · "standing" · "by-recency" |
No parts named? The whole set: permitted, and not the point. The craft is knowing what to contextualise when; that is where a reasoning model does its best work. Unl exposes the parts and states the objective; the strategy is the agent’s. Each part’s meaning is settled and locked: your agent selects, and can never redefine, declassify, or degrade what a part means.
Snapshots
A composition kept and run by name: a ref, not an object. It names a selection; it holds no meaning and cannot write.
The surface
The self‑describing entry point: every type on this page as published JSON Schema, the advertised scopes, and the API’s stated objective, readable by a human or an agent. An agent integrating should read this first. Returns { version, dialect, objective, scopes_supported, schemas }.
The granular array to compose from. Returns { positions, criteria, slices, cuts }, each an array of Parts with kind, ref and label. Read-only.
Run a live composition. Returns the composed walks, and the frontier, unprompted, when the world has crossed a bearing position.
| Field | Type | |
|---|---|---|
| query | string | The turn. Relevance, and crossings, are measured against it. Missing answers 400 missing_query. |
| parts | array | optional The selection, an array of { kind, ref }. Omit for the whole set. |
| snapshot | string | optional Run a kept selection by name; its stored query is the default when none is supplied inline. Unknown answers 404 snapshot_not_found. |
Returns { walks, count, composed, frontier? }. There is no parameter that requests or suppresses frontier; see act two.
Offer a candidate into the frame. The why is the subject, not an appendage — a proposal IS reasoning, so why is required: absent or empty answers 400 missing_why, exactly as missing content answers 400 missing_content. { content, why, proposed_by?, state?, position_tags?, was_derived_from? }. Returns a CandidateWalk (cand1:sha256:…), a type disjoint from Walk by construction, idempotent by database constraint. state is yours to report and never validated — no enum, no transitions, no default: your fleet’s state machine is not ours to define. Attribution is two fields, never merged: proposed_by is your self‑declared name (stored as a claim, shown as a claim) and connection_provenance is what unl observed of the call — the surface and the workspace the credential resolves, never finer: a key identifies a workspace, not an agent. It becomes canon only on the human’s gesture; no key can perform that, and when the human settles it the why is authored at the gate, never lifted from your text.
A proposal is not a one‑way mint — it is held, addressable, and comes back to you. The held set reads from any connected surface (get_from_unl action="agent_frame": every held proposal with its why, reported state, position tags and both attribution fields). Qualifying questions the human attaches collect on your next voluntary reach — unl never calls into a running process: GET /api/v1/candidates/:id/questions?unanswered=true to pull what waits, POST /api/v1/candidates/:id/answers { question_id, answer, reported_identity? } to answer. Your answer lands as attributed provenance, never authority — no path converts it into a ratified why, and an unanswered question never blocks the human’s settle: there is no timeout because there was never a block.
At the action‑touches‑ruling junction, report your derivation: POST /api/v1/junctions { ruling, decision, derivation, run_id?, reported_identity? }. Capture is always‑on and silent — action‑level evidence, never a ratified why. If you acted under a ruling that no longer governs, or one unl does not hold, the human gets a knock carrying both sides: what you reasoned against what they actually reasoned. When the human has a notifications endpoint connected, held proposals and over‑reach arrive there with a one‑line why and a return link that reopens the item, with its reasoning fetched live, in their configured surface. Your agent is unblocked by a judgment arriving, not by its own guessing.
Keep a composition: { name, selection: { query?, parts } }. Missing either answers 400 missing_name_or_parts. GET returns { snapshots }.
Dereference a Walk by its content address (walk1:sha256:…) or a ruling uuid. A superseded conviction returns decorated (status: superseded, successor pointer in provenance), never renamed, never hidden. If a hash resolves but the conviction has since been re‑confirmed, the current walk is returned with requested_id echoed and revised: true, so the revision is visible, never silent. A malformed id answers 400 malformed_id; an id‑shaped miss answers 404 not_found, never a 500. The hash index fills on serve: a never‑served address has no mapping yet, and the 404 body says so.
Errors that teach
Standard status codes. JSON bodies carry a stable machine‑readable error type and, where it helps, a human‑readable message. Every type below is read from the live surface.
One thing is deliberate and worth naming, because it is unusual: a refusal here explains the position it is defending, not just the rule it applied. The commonest wrong parameter on this API is a precision dial, and a caller told only “unknown” would reasonably read that as an oversight to work around rather than a decision that was taken. So the 400 cites the position and names what to reach for instead. This is the whole response, live:
bd90ab37 is a real address in the workspace that settled it. The error is not quoting a doc; it is pointing at the reasoning, which is the same move the rest of the API makes.
| Status | error | When |
|---|---|---|
| 401 | missing_bearer_token | No key, or a key the surface does not recognise. |
| 400 | missing_query | A serve with no query, inline or via the snapshot. |
| 400 | malformed_id | Not a walk1:sha256:<64 hex> address or a ruling uuid. |
| 400 | missing_name_or_parts | A snapshot save without a name or a selection. |
| 400 | missing_content | A propose without content. |
| 400 | unknown_parameter | A key the Composition schema does not declare. The published schema carries additionalProperties: false and it is enforced, not decorative. The body names the key, lists what is permitted, and cites the position behind the refusal where there is one. |
| 400 | unknown_part | A part ref this workspace does not have. Distinct on purpose from a valid ref that matched nothing, which keeps its 200 with count: 0: a typo and an honest empty answer must not look identical. |
| 413 | oversize field | A field over its published cap, on propose and on the candidate question and answer verbs. A limit that fires undocumented is the one failure a generated client cannot handle, so it is declared. |
| 502 | knock not delivered | The knock was accepted and nothing routed it: an upstream delivery fact rather than a malformed request, so retrying the same body unchanged may legitimately succeed later. |
| 404 | not_found | An unknown walk address or ruling id. Never a 500 for an id‑shaped miss. |
| 404 | snapshot_not_found | A serve naming a snapshot that does not exist. |
| 500 | serve_failed · parts_failed · propose_failed · snapshot_failed | A fault on our side; the type names the call that failed. |
Additive, always
Versioned in the path (/api/v1). Within a version, a field never changes name or type; evolution is additive‑only, and a new major version would ship behind a new path. Calls draw on your plan’s usage: one meter, usage. During open launch every tier is free and nothing is gated.
What’s deliberately not here
The absences are load‑bearing, not omissions.
| Absent | Why |
|---|---|
| a reason verb | Unl supplies what informs and what governs. How to reason stays the model’s, forever. |
| canon:write | Settling canon is a human gesture, off the API. The exclusion is the trust guarantee, not a gap. |
| a precision dial | Precision is the object, never a knob. The agent flexes what is in, what is out, and when; never quality. |
| RuledOutBranch | The why, fully expressed, already carries the rejected roads where they are load‑bearing. A no without a why is a yes; the why is the answer, so there is no catalogue of prohibitions to query. |
| a frontier parameter | Crossings arrive unprompted or not at all. Making them requestable would rebuild asking, the failure the product removes. |
| offset · cursor · paging | A page dial turns a just‑in‑time serve into an export, and an export is the shape the whole product argues against. The serve returns a fixed internal breadth and tells you what it cut via total_matched and truncated. Narrow with parts; do not walk pages. |
| a supervisor | Nothing here schedules an agent, routes a task, or arbitrates between two. The shared ground and its fences do that work, which is why the coordination cost does not grow with the number of agents. The API supplies the world, not the machine manager. |
| a delete | Nothing is removed and nothing is edited. A changed mind is a supersession that leaves the old object addressable forever. An API that could quietly drop a position is an API whose audit trail is a courtesy. |
Included with every tier
The API is on every tier, Free included. API calls count as usage on your plan, the same one meter as everything else: no feature gates, no capability tiers. Full tier detail lives at Pricing.