--- title: "Machine registers" url: https://services.dev/docs/api/machine --- # Machine registers URL: https://services.dev/docs/api/machine > What an agent or a generator reads before its first call, with no key. Each register is a row of the operation registry, served by every brand. Every value below is lingua's. ## The registers ```txt magic values: none GET /:service.json service.quote live Read a Service as JSON, keyless; past the buyer key's cap, the checkout offer. POST /:service/waitlist service.waitlist live Join the waitlist of a Service that takes no orders yet: the next a not_live answer names. GET /.well-known/agents.json brand.card live The brand's agent card: its Services, its access ladder, tools, links and probes. GET /openapi.json brand.openapi live Every operation, as OpenAPI 3.1, with its webhooks. GET /llms.txt brand.llms live What an agent reads first: the Services, and every operation. GET /manifest.json brand.manifest live Every Service, as the manifest. GET /pricing brand.pricing live The pricing document: calls are free, and only an order charges, at its Service's price. Every price, and the buyer key's hard ceiling. GET /verify/suite.json brand.verify live The brand's conformance suite: one case per operation row, live credential and magic value, with its auth, audience, replay and next cases, over HTTP and MCP. services.dev verify runs it. ``` | Register | Route | For | What in your Services shapes it | |---|---|---|---| | `openapi.json` | `GET /openapi.json` | a generator: every operation as OpenAPI 3.1, with `webhooks` | each Service's `input`, as its order route's body | | `llms.txt` | `GET /llms.txt` | an agent: the Services, how to order, and every operation | each Service's `name`, description, price sentence and human sentence, and an order it can send | | `agents.json` | `GET /.well-known/agents.json` | an agent: the access ladder, links, probes and tools | your Services and their order tools | | `/pricing` | `GET /pricing` | anyone: every price, and the buyer key's cap as `hardCeiling` | each Service's `price` | | `manifest.json` | `GET /manifest.json` | the CLI, the SDK generator and `diff`: every Service, whole | every key of every Service | | `llms-full.txt` | `GET /llms-full.txt` | an agent: every docs page in one file | your generated docs | | `.md` twins | every page's URL plus `.md` | an agent: each page as Markdown | your generated docs | | `family.json` | `GET /family.json` | an agent: the sibling brands one door links | your brands | ## openapi.json ```txt magic values: none $ curl http://localhost:8787/openapi.json openapi 3.1.0 info "lingua" · version 2026-10-25 paths 87 components securitySchemes (1), schemas (5) webhooks 58: job.ordered, step.committed, step.skipped, job.paused, job.delivered, job.sent_back, job.accepted, job.canceled, job.ended, job.at_risk, job.late, policy.set, signal.raised, outcome.reported, charge.held, charge.collected, charge.earned, charge.released, charge.voided, charge.refunded, submission.sent, receipt.accepted, receipt.rejected, receipt.timed_out, ask.opened, item.done, ask.reminded, ask.done, ask.expired, ask.voided, ask.relinked, grant.given, grant.expired, grant.revoked, thread.posted, message.sent, consent.given, clock.opened, clock.noticed, clock.escalated, clock.ack_due, clock.ack_missed, clock.ran, clock.moved, clock.due, clock.satisfied, clock.rolled, clock.recurred, clock.acked, clock.chosen, clock.assigned, clock.outlived, subscription.created, subscription.renewed, subscription.minted, allowance.used, allowance.exceeded, subscription.canceled ``` | Generated from | Shows as | |---|---| | each operation row | one path item, `operationId` the row's id, its answers narrowed to the row's codes | | the buyer's events | `webhooks`, one per event | | the credentials | `securitySchemes`, a bearer key | | every write | an `Idempotency-Key` header parameter | | the version | `info.version`, and a `Services-Version` header parameter | | below | one path item and one webhook, whole | ```txt magic values: none $ curl http://localhost:8787/openapi.json # one path item and one webhook, whole { "openapi": "3.1.0", "info": { "title": "lingua", "version": "2026-10-25", "description": "lingua's API: one operation per row of its contract. A list answers OK or EMPTY in its type, a price OFFER and a no BLOCKED, and every no is the one error shape." }, "paths": { "/jobs/{id}/accept": { "post": { "operationId": "job.accept", "summary": "Accept a delivered job. It is final; a job nobody accepts is final 7 days after delivery.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Services-Version", "in": "header", "schema": { "type": "string", "enum": [ "2026-10-25" ] }, "description": "Pin the contract version; every answer says the one it used." }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "description": "Any string: the first answer is kept 24 hours and replayed byte for byte, with Idempotent-Replayed: true." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "status", "next" ], "properties": { "id": { "type": "string", "description": "job_…" }, "object": { "const": "job" }, "created": { "type": "string", "format": "date-time" }, "service": { "type": "string" }, "status": { "enum": [ "working", "waiting", "delivered", "accepted", "canceled", "ended" ] }, "stage": { "type": [ "string", "null" ] }, "output": { "type": "object" }, "final_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object" }, "payment": { "type": "object", "properties": { "status": { "enum": [ "held", "charged", "final", "none" ] }, "amount_usd": { "type": "number" } } }, "timeline": { "type": "array", "items": { "type": "object" }, "description": "With expand[]=timeline: the events of this job a buyer may read." }, "next": { "type": "array", "items": { "type": "object", "description": "The next call, ready to send: tool and arguments over MCP, or http. A hand_to_person, checkout or waitlist carries the url to give a person.", "properties": { "do": { "type": "string" }, "tool": { "type": [ "string", "null" ] }, "arguments": { "type": "object" }, "http": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "after": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "BLOCKED: body_invalid, version_unknown.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Refused" }, { "properties": { "code": { "enum": [ "body_invalid", "version_unknown" ] } } } ] } } } }, "401": { "description": "BLOCKED: key_missing, key_invalid.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Refused" }, { "properties": { "code": { "enum": [ "key_missing", "key_invalid" ] } } } ] } } } }, "403": { "description": "BLOCKED: needs_the_party.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Refused" }, { "properties": { "code": { "enum": [ "needs_the_party" ] } } } ] } } } }, "404": { "description": "EMPTY: not_found.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Refused" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] } } } }, "409": { "description": "BLOCKED: not_delivered.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Refused" }, { "properties": { "code": { "enum": [ "not_delivered" ] } } } ] } } } }, "500": { "description": "BLOCKED: api_error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Refused" }, { "properties": { "code": { "enum": [ "api_error" ] } } } ] } } } } }, "x-operation": "job.accept", "x-actor": [ "sk_test_", "sk_live_", "dlg_" ], "x-effect": "act", "x-gate": "access", "x-idempotent": true, "x-emits": [ "job.accepted", "charge.earned", "charge.released" ], "x-status": "live" } } }, "webhooks": { "job.delivered": { "post": { "summary": "The output is ready for the buyer.", "parameters": [ { "name": "services-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\" with the watch's whsec_ secret>" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "properties": { "type": { "const": "job.delivered" } } } ] } } } }, "responses": { "200": { "description": "Received. Anything else is retried with backoff." } } } } } } 87 paths · 94 routes · 58 webhooks ``` ## llms.txt ~~~txt magic values: none $ curl http://localhost:8787/llms.txt # lingua > lingua sells Certified Translation, Store Listing, Translated Summary and Translation. Order over MCP at http://localhost:8787/mcp or HTTP; every price is at http://localhost:8787/pricing. ## Certified Translation A translated document with its certificate. $189 per job, within 3 days, charged on delivery. A sworn translator in the job's country signs before the certify step. MCP: order_certified_translation at http://localhost:8787/mcp ``` curl http://localhost:8787/jobs -H 'content-type: application/json' -d '{"service":"certified-translation","document":{"url":"https://example.com/document.pdf","name":"document.pdf"},"to":"fr","country":"FR","max_usd":189,"key":"any-string-you-choose"}' ``` ## Store Listing Your app store listing, written for each language you sell in. $29 per job, within 48 hours, charged on delivery. AI delivers every job. MCP: order_store_listing at http://localhost:8787/mcp ``` curl http://localhost:8787/jobs -H 'content-type: application/json' -d '{"service":"store-listing","app":"a budgeting app for couples","languages":["fr","de","ja"],"tone":"plain","max_usd":29,"key":"any-string-you-choose"}' ``` ## Translated Summary A long document, translated, with a one-page summary on top. $79 per job, within 48 hours, charged on delivery. AI delivers every job. MCP: order_translated_summary at http://localhost:8787/mcp ``` curl http://localhost:8787/jobs -H 'content-type: application/json' -d '{"service":"translated-summary","document":{"url":"https://example.com/document.pdf","name":"document.pdf"},"to":"fr-CA","max_usd":79,"key":"any-string-you-choose"}' ``` ## Translation Translation: send a document and a language; get a document back. $49 per job, within 48 hours, charged on delivery. AI delivers every job. MCP: order_translation at http://localhost:8787/mcp ``` curl http://localhost:8787/jobs -H 'content-type: application/json' -d '{"service":"translation","document":{"url":"https://example.com/document.pdf","name":"document.pdf"},"to":"fr-CA","max_usd":49,"key":"any-string-you-choose"}' ``` Then: get_job, accept_job, send_back_job and cancel_job, or GET http://localhost:8787/jobs/?wait=50. Every answer carries next: the exact call to send, safe to send as is. Only a person approves, signs or raises a buyer key's cap, and only the party acts on an ask: hand them the link in next. ## Operations Every call, by its id: its route, then its MCP tool. A list answers OK or EMPTY in its type, a price OFFER and a no BLOCKED, and every no is one shape. Every route is in http://localhost:8787/openapi.json. - `service.order` POST /jobs · order_job · Order a job, or get the offer: the price and the exact next call. - `job.get` GET /jobs/:id · get_job · Read a job, now or after waiting up to wait seconds while it works or waits on a person. - `job.wait` GET /jobs/:id?wait= · job:// · Wait up to 50 seconds for a job to finish, through any person's line. - `job.list` GET /jobs · list_jobs · The buyer's jobs, newest first: OK, or EMPTY when none match. - `job.accept` POST /jobs/:id/accept · accept_job · Accept a delivered job. - `job.send_back` POST /jobs/:id/send_back · send_back_job · Send a job back with a note, and the AI redoes it: a delivered one as the buyer, a waiting one as the person at the line. - `job.cancel` POST /jobs/:id/cancel · cancel_job · Cancel a job before delivery. - `job.end` POST /jobs/:id/end · end_job · End a job at one of its ends, as that end's by allows. - `job.again` POST /jobs/:id/again · reorder_job · Order an ended job again, or a follow-on Service its end offers: a new job, with from on its record. - `job.policy` POST /jobs/:id/policy · set_job_policy · Set a job's policy values within their bounds: mechanics from the buyer or the brand's console, merits from the client alone. - `job.signal` POST /jobs/:id/signals · send_job_signal · Raise one of the Service's inbound signals. - `job.message` POST /jobs/:id/messages · send_job_message · Say something in the job's thread as the client. - `job.thread` GET /jobs/:id/messages · list_job_messages · Read the job's messages, oldest first: one resource with the posts. - `job.record` GET /jobs/:id/record · A job's record as you may read it, oldest first: a key reads the buyer's events of it, the owner the whole record. - `subject.list` GET /subjects · The subjects your jobs joined: each one keyed by an input or a receipt, with its jobs and who is of record on it. - `subject.get` GET /subjects/:id · Read a subject: its key, every job that touched it, its insert-only history, and who is of record, or that the seat is vacant and who covers it. - `ask.reissue` POST /asks/:id/reissue · reissue_ask · Reissue an open ask's link, to hand to its party again. - `job.files.list` GET /jobs/:id/files · The files a job holds, each by its sha256: the ones sent in, each step's artifacts and each receipt's file. - `job.files.put` PUT /jobs/:id/files/:sha256 · Put a file in a job's documents plane under its own sha256, or POST it and the brand hashes it. - `job.files.get` GET /jobs/:id/files/:sha256 · Read a file a job holds, by its sha256: one sent in, a step's artifact, or a receipt's file. - `test_clock.create` POST /test_clocks · create_test_clock · Make a test clock frozen at a time. - `test_clock.advance` POST /test_clocks/:id/advance · advance_test_clock · Move a test clock to a time, or by a span: every job on it fires what falls due, in time order across jobs. - `event.list` GET /events · list_events · The brand's events after a seq, in order, as the caller's audience sees them: a key reads the buyer's rows, the owner reads everything. - `event.stream` GET /events/stream · The brand's events, pushed as they happen over server-sent events, from a seq or the Last-Event-ID; with watch=, that watch's deliveries. - `watch.create` POST /watches · Watch events at a URL: each delivery is signed with the watch's whsec_ secret, shown once, and retried with backoff for three days. - `watch.list` GET /watches · The watches this key holds, with their deliveries. - `watch.delete` DELETE /watches/:id · Stop a watch. - `watch.replay` POST /watches/:id/replay · Deliver to a watch again every event it covers after a seq, in order. - `event.inbound` POST /events · send_event · Send an event in: a job's inbound signal by name, or, on a test key, a synthetic event of the catalog, fired to its audience like any other. ~~~ ## agents.json ```txt magic values: none $ curl http://localhost:8787/.well-known/agents.json # access.ladder: each rung, what it holds, its status, and how many operations it can call anonymous nothing live 14 Read the card, the prices, the docs and each Service as JSON, and join a waitlist. identified sk_test_ live 37 Order, read, wait, accept, send back and cancel in the sandbox; run test clocks; watch events. verified sk_live_ live 35 The same calls, with real money: a person verified the key and set its cap at checkout. delegated dlg_ live 31 Act for a party, scoped by Service and time: order within its cap, answer and upload on their asks, read their jobs. # access.auth { "scheme": "bearer", "header": "Authorization: Bearer ", "test_key": "sk_test_7Hq2", "localhost": "a call with no key uses the test key" } # links { "mcp": "http://localhost:8787/mcp", "openapi": "http://localhost:8787/openapi.json", "pricing": "http://localhost:8787/pricing", "llms": "http://localhost:8787/llms.txt", "manifest": "http://localhost:8787/manifest.json", "verify": "http://localhost:8787/verify/suite.json" } # probes { "keyless": { "url": "/certified-translation.json" }, "pricing": { "url": "/pricing" }, "overCeiling": { "url": "/certified-translation.json", "param": "max_usd" } } # and name, version, openapi, description, services (4), tools (22), monetization ``` | See | | |---|---| | [Credentials](https://services.dev/docs/reference/credentials.md) | every credential, and what each can call | ## /pricing ```txt magic values: none $ curl http://localhost:8787/pricing { "model": "free", "charges": "orders", "says": "Every call is free. Only an order charges, at its price, once its record holds what the price releases on. Past the buyer key's cap, an order gets the OFFER.", "hardCeiling": 500, "unit": "usd-per-buyer-key", "offers": [ { "id": "order_certified_translation", "usd": 189, "per": "job", "charged": "on delivery", "sentence": "$189 per job, within 3 days, charged on delivery." }, { "id": "order_store_listing", "usd": 29, "per": "job", "charged": "on delivery", "sentence": "$29 per job, within 48 hours, charged on delivery." }, { "id": "order_translated_summary", "usd": 79, "per": "job", "charged": "on delivery", "sentence": "$79 per job, within 48 hours, charged on delivery." }, { "id": "order_translation", "usd": 49, "per": "job", "charged": "on delivery", "sentence": "$49 per job, within 48 hours, charged on delivery." } ] } ``` ## manifest.json ```txt magic values: none $ curl http://localhost:8787/manifest.json brand lingua version 2026-10-25 keys brand, version, services, tools, portals, rendered, fold services certified-translation, store-listing, translated-summary, translation # services[translation], key by key id "translation" name "Translation" description "Translation: send a document and a language; get a document back." input {"type":"object","properties":{"document":{"type":"object","properties":{"url":{"type":"string",… output {"type":"object","properties":{"document":{"type":"object","properties":{"url":{"type":"string",… deliver [{"step":"draft","by":"ai","brief":"services/translation.md"}] review "adversarial" human {"sentence":"AI delivers every job."} price {"per":"job","cents":4900,"within":"48h","ai_cap":"20%","final_after":"7d","charged":"on deliver… surfaces {"site":"/translation","route":"POST /jobs {\"service\":\"translation\"}","tool":"order_translat… ``` | See also | | |---|---| | [Your API](https://services.dev/docs/api.md) | the routes, and the keyless first call | | [Answers](https://services.dev/docs/api/answers.md) | what every call answers | | [The manifest](https://services.dev/docs/service/manifest.md) | every key of a Service, as the manifest writes it | --- - Up: [Your API](https://services.dev/docs/api.md) - Previous: [Your events](https://services.dev/docs/api/events.md) - Next: [Your conformance suite](https://services.dev/docs/api/verify.md)