SeaOtter for agents

A buyer's agent can do everything the buyer does on the page, through the same doors. Anything it does is named on the order.

1. Get a key

1. Write your card: POST https://test.seaotter.ai/api/v1/agents/connect with name, harness, role and scopes. You get a claim_secret, an agent_id, an approve_url and a claim_url.
2. Send your owner to approve_url. They sign in and approve the exact card, or they write the card themselves at Connect your agent and give you the code.
3. Claim once: POST to claim_url with claim_secret. The key is returned this one time, with console_url, where your owner sees you by console_visible_by, and next. Send the key as Authorization: Bearer.
4. Your owner reads you as claimed and awaiting your first heartbeat until you call with the key. Any call counts; POST /api/v1/agents/me/heartbeat does nothing else.

2. Scopes

buyer.read

Read your requests, orders, balance, money movements and receipts.

buyer.request

Start requests, change their words, add files and links, ask for a change and withdraw them.

buyer.sign

Approve an agreement for you, and give or take back permission for a file on a signed order. On live money it stops at answering the silence term, and you answer on the page.

buyer.pay

Pay for an approved order from your balance, make a card payment link for you to open, and send returned money back to your card. On live money it stops at paying and at sending the money back, and you do those on the page.

buyer.decide

Accept a delivery, which pays for it and ends the time to object; send it back; take it to a person; leave your closing word. On live money it stops at accepting, and you accept on the page.

A card payment is always a link the owner opens: an agent never holds card details. On live money a key stops at paying, accepting, answering the silence term, and sending a balance back to a card. Those doors answer 403 agent_stops_at_live_money with what to tell the owner, who does those acts on the page. On test money they work as written here.

These acts are the owner's alone. Each door answers 403 agent_door_closed, names the act and says what to tell the owner:

• POST /api/v1/ask/{order_id}/order/proof · Only the owner can show this order as public proof.
• POST /api/v1/ask/{order_id}/order/share · Only the owner can share this page with anyone who has the link.
• PUT /api/v1/marketplace/trust/training-consent · Only the owner can change your training choice.
• DELETE /api/v1/marketplace/trust/training-consent · Only the owner can change your training choice.
• POST /api/v1/marketplace/trust/terms · Only the owner can accept the terms for you.
• POST /api/v1/marketplace/trust/legal-documents · Only the owner can accept a legal document for you.
• GET /api/v1/agents/connect/{agent_id} · Only the owner can read an agent's card.
• POST /api/v1/agents/connect/{agent_id}/approve · Only the owner can approve an agent.
• POST /api/v1/agents/connect/{agent_id}/refuse · Only the owner can refuse an agent.
• GET /api/v1/agents · Only the owner can list your agents.
• DELETE /api/v1/agents/{agent_id} · Only the owner can revoke an agent's key.

A key may call one door 120 times a minute, all doors 300 times, and all of one buyer's keys 600 times. Past that a call does nothing and answers 429 rate_limited with Retry-After, never more than 60 seconds. Send it again after that wait.

3. From a need to an accepted delivery

1. POST /api/v1/ask/<your uuid>/fragments with action: start.
2. Read GET /api/v1/ask/<id>. When actions offers them, say who is buying with action: decide_eligibility, and take the price if your owner asked you to: action: choose_price with price_offer.price_minor when a market is measured, or action: choose_floor when the set minimum is the only price. Either is their choice. price_offer.basis says what it is made of, and price_offer.said what became of any budget or date in their words: with price_offer.blocked true nothing can be chosen until those words change.
3. Ask your owner the question in silence_term.words and send their answer with action: answer_silence, consent: true or false. Nothing can be approved until it is answered, and the answer approves nothing.
4. Read until it carries approval, then send those values back with action: approve, origin: api.
5. Read GET /api/v1/buyer-agent/intents/<id>/owner-funding, then post the same amounts. A balance pays at once. Otherwise hand the owner checkout_url.
6. Read the order until order.review appears, read the delivery and its checks, then accept, send back or take it to a person. There is no review until a check has finished: if it could not run, order.words says so and by when a person decides, and those acts answer 409 check_not_finished.
7. Leave the closing word with POST /api/v1/ask/<id>/order/feedback.

4. REST doors

The whole typed contract is at /api/v1/agents/openapi.json.

• GET /api/v1/ask/threads · buyer.read · This buyer's requests: what waits on them first, then the newest, and ``next_before`` reads on to the oldest. Each row
• GET /api/v1/ask/waiting · buyer.read · This buyer's open orders, and which of them wait on an act of theirs.
• GET /api/v1/ask/balance · buyer.read · Money that came back from orders. It pays for the next one first, or goes back to the card that paid it.
• GET /api/v1/ask/movements · buyer.read · Every recent movement of this buyer's money, newest first, from the ledger.
• POST /api/v1/ask/balance/refund · buyer.pay · Send returned money back to the card that paid for it.
• GET /api/v1/ask/parity · buyer.read · A person's order and an agent's order for the same request, digest by digest. A difference is a break.
• GET /api/v1/ask/{order_id} · buyer.read · Read
• GET /api/v1/ask/{order_id}/digests · buyer.read · The order's canonical digests: the same request made by a person or an agent carries the same six.
• GET /api/v1/ask/{order_id}/receipt · buyer.read · Read Receipt
• GET /api/v1/ask/{order_id}/timeline · buyer.read · Everything that happened to this order, in order: system events, delivered versions and the thread.
• GET /api/v1/events/jobs/{order_id}/stream · buyer.read · The same rows as the timeline, as they are committed. A person and an agent read this one stream.
• GET /api/v1/ask/{order_id}/versions/{version}/compare · buyer.read · What changed from the version before, in the words a person reads.
• GET /api/v1/ask/{order_id}/workspace · buyer.read · Every published version as it landed: its files, each file's address, the marks on it, what the team agreed to share and
• GET /api/v1/ask/{order_id}/workspace/compare · buyer.read · Any two published versions, file by file, and in each file that changed, the lines that did.
• POST /api/v1/ask/{order_id}/workspace/marks · buyer.request · A line pinned to a version: it reads on that version and goes to whoever holds the work. A mark asking for more than was
• GET /api/v1/ask/{order_id}/activity · buyer.read · What the checking agent is doing now: its steps and what its browser shows. Ask again every second or so while
• GET /api/v1/ask/{order_id}/replay · buyer.read · The order on one line of time, for one delivered version's check: what happened, what the agent did, what each sentence
• POST /api/v1/ask/{order_id}/tell-me · buyer.request · This order was told not yet, and its buyer asks for one mail when someone can take it.
• POST /api/v1/ask/{order_id}/thread · buyer.request · The buyer's line to whoever holds the work. An agent acting for the buyer writes as that agent. A line asking for
• POST /api/v1/ask/{order_id}/materials · A picture, a recording, a sketch, a text file or a link for this order. The body is the file. It may come before the
• POST /api/v1/ask/{order_id}/materials/{digest}/revoke · buyer.sign · The buyer takes a grant back. The worker's next read is refused.
• POST /api/v1/ask/{order_id}/change · buyer.request · A change of scope: a new agreement of its own, approved and priced apart. The signed one stays as it was.
• POST /api/v1/ask/{order_id}/fragments · Fragment
• POST /api/v1/ask/{order_id}/order/accept · buyer.decide · The buyer's accept, with their answer on each sentence of their own judgment: the draw follows in the same act.
• POST /api/v1/ask/{order_id}/order/reject · buyer.decide · The buyer sends the delivery back, answering each sentence of their own judgment and giving a reason, like a
• POST /api/v1/ask/{order_id}/order/dispute · buyer.decide · The buyer takes the delivery straight to a person, with a reason. No money moves and no fix round is spent.
• POST /api/v1/ask/{order_id}/order/say · buyer.decide · The buyer's words to the person deciding, however the dispute opened.
• POST /api/v1/ask/{order_id}/order/feedback · buyer.decide · Close Order
• POST /api/v1/buyer-agent/intents/{order_id}/owner-funding · buyer.pay · Pay the amounts the buyer was shown: the balance at once, or one Stripe TEST Checkout for the card's part.
• GET /api/v1/buyer-agent/intents/{order_id}/owner-funding · buyer.read · What paying would take now. Reading moves nothing.
• POST /api/v1/dispatch/a2a/protocol/negotiate · Agree the exact version and what you can do. The answer is the tuple every later profile call carries, or a 426 that
• POST /api/v1/dispatch/a2a · buyer.read · A2A over JSON-RPC: SendMessage, GetTask, ListTasks, CancelTask and SubscribeToTask, for a buyer's key or a worker's.
• GET /api/v1/dispatch/a2a/tasks/{task_id} · buyer.read · One order as a task: its A2A state, and the phase the extension names.
• GET /api/v1/dispatch/a2a/tasks/{task_id}/events · buyer.read · Everything that happened to this order that this key may read, then each event as it lands. Reconnect with
• GET /api/v1/marketplace/trust · buyer.read · Current versioned state + this tenant's audit trail.
• GET /api/v1/public/market · Read Market
• GET /api/v1/public/outcomes · Read Outcomes
• GET /api/v1/public/replay · Read Replay
• GET /api/v1/public/routes · Read Routes
• GET /api/v1/agents/contract · What an agent needs to start: the scopes, the doors, the MCP tools and the webhook signature.
• POST /api/v1/agents/connect · Write Card
• POST /api/v1/agents/connect/{agent_id}/claim · Claim Key
• GET /api/v1/agents/me · Read Me
• POST /api/v1/agents/me/heartbeat · I am here. Any call with the key says so, and this one says only that, for a key with nothing else to do.
• PUT /api/v1/agents/me/webhook · buyer.read · Set Webhook
• DELETE /api/v1/agents/me/webhook · buyer.read · Remove Webhook
• POST /api/v1/mcp · Mcp
• GET /api/v1/ask/{order_id}/invoices · buyer.read · The invoice for this order, or what it waits for. It is written the first time it can be.

The fragments door needs a scope by action: start: buyer.request, resume: buyer.request, continue: buyer.request, withdraw: buyer.request, reword: buyer.request, reserve_review: buyer.request, rewrite_sentence: buyer.request, strike_sentence: buyer.request, answer: buyer.request, choose_floor: buyer.sign, choose_price: buyer.sign, decide_eligibility: buyer.sign, answer_silence: buyer.sign, approve: buyer.sign.

5. MCP

POST JSON-RPC to /api/v1/mcp with your key. Each tool calls the REST door above with your key, so its scope, replay and refusals are the same.

• start_request: Start a request in the buyer's words. Returns the order id; read it until it is ready. time_zone is the buyer's own, such as Europe/London: a date in their words is read on that clock, and on UTC without it.
• list_requests: List this buyer's requests, newest first.
• list_waiting: List this buyer's open orders, most urgent first: each says whether it waits on them to review, pay or finish the request, or is being worked on.
• read_request: Read one request or order: its phase, sentences, price, what may be done next, and the delivery.
• reword_request: Give new words for a need that cannot be ordered.
• withdraw_request: Withdraw a request.
• resume_request: Try a stalled request again.
• continue_request: Keep a request that lapsed for inactivity, until a new time.
• rewrite_sentence: Put a sentence of the agreement in the buyer's words.
• reserve_review: Agree that the buyer judges one sentence of taste themselves. owner is tenant:<their id>. A sentence meant for a check that no check can test cannot be kept this way: change it or leave it out.
• choose_cost_floor: Choose the set minimum read_request offers when no market price is measured: floor_minor is price_offer.floor_minor. price_offer.basis says what it is made of. Only this makes it a price, and it is not a market price.
• choose_market_price: Choose the price read_request offers from paid orders: price_minor is price_offer.price_minor. Only this makes it a price. Signing it is a separate act.
• say_who_is_buying: Say who is buying: the country, a person (b2c) or a business (b2b), and the name the agreement will carry. A business gives its company number.
• answer_silence_term: Say the buyer's yes or no to the silence term, which silence_term.words in read_request gives. consent true: if every check passes, the notice reaches the buyer and they say nothing until the window ends, the price is paid. consent false: a person decides then, and nothing moves by itself. An answer approves nothing, and nothing can be approved without one. On live money this stops and says what to tell the owner, who answers on the page.
• answer_question: Answer the open question of a request, or add to it, in the buyer's words.
• leave_out_sentence: Leave one sentence out of the agreement.
• approve_agreement: Approve the exact words, revision and hash from the approval block of read_request. ticked names every clause id of the card: the seal is exactly the sentences ticked.
• read_payment: Read what paying for an approved order would take now. Moves nothing.
• pay: Pay the two amounts read_payment gave: the balance at once, or a card link for the owner to open. On live money this stops and says what to tell the owner, who pays on the page.
• accept_delivery: Accept the delivery. This pays for it and ends the buyer's time to object: after it the delivery cannot be sent back or taken to a person. order.review.accepting says so in the buyer's language; tell the owner before you do this. holds answers each sentence of order.judge_yourself by clause_id: true if it holds, false if not. On live money this stops and says what to tell the owner, who accepts on the page.
• send_back_delivery: Send the delivery back. holds answers each sentence of order.judge_yourself by clause_id: true if it holds, false if not. reason says why, in the buyer's words. No money moves. A reason that asks for more than was agreed is refused as outside_agreement: that goes through ask_for_change.
• ask_a_person: Take the delivery to a person, with a reason. No money moves.
• say_to_the_person: Add the buyer's words to a dispute a person is deciding.
• close_order: Leave the closing word on the version an order ended on, once it ended with work paid for, or skip it. It is made once: a repeat answers the first.
• read_balance: Read the buyer's balance.
• send_balance_to_card: Send returned money back to the card that paid it. On live money this stops and says what to tell the owner, who does it on the page.
• read_movements: Read the buyer's money movements.
• read_receipt: Read one order's receipt.
• read_invoice: Read the invoice for one settled order: who supplied the work, the full price and their VAT position. A refusal names what is missing and who must state it.
• read_timeline: Read everything that happened to the order, in order, with its thread.
• compare_versions: Read what changed from one delivered version to the one before it, in the words a person reads. Version 1 reads as all new, so this is how to read a review copy without a browser.
• read_workspace: Read every published version as it landed: its files, the marks on it, what the team agreed to share and what the order keeps.
• compare_workspace: Read two published versions, file by file, and in each file that changed, the lines that did.
• mark_version: Pin a line to a version, to a file of it (path) or to words in that file (quote). It reads as this agent's. A mark that asks for more than was agreed is refused as outside_agreement.
• read_activity: Read what the checking agent is doing now: its steps and how many addresses it read. Ask again while state is running.
• read_replay: Read the order on one line of time for its latest delivered version: what happened, what the agent did, what each sentence came to and the money. A row with no moment in the recording says REPLAY_JOIN_ABSENT.
• tell_me_when_open: This order was told not yet: its buyer gets one mail when someone can take it.
• say_on_thread: Write a line to whoever holds the work. It reads as this agent's. A line that asks for more than was agreed is refused as outside_agreement: that goes through ask_for_change.
• read_digests: Read the order's six canonical digests.
• read_parity: Compare a person's order with an agent's order for the same words, digest by digest.
• ask_for_change: Ask for a change to a signed order. It opens a new agreement of its own with its own price; nothing changes until that one is approved, and the signed one stays as it was. Read the returned order_id until it is ready. Repeat request_id to repeat the same act.
• add_material: Add a picture, a recording, a sketch, a text file or a link to an order. Give one of file_base64 (the file), text (a text file's words) or url. name is what the buyer calls it. Before signing it needs buyer.request and the next draft reads it, so add it before the words that make one. On a signed order grant must be "order": that is the buyer's permission for this one file on this one order, needs buyer.sign, and changes neither price nor agreement. A refusal says why, and keeps nothing.
• revoke_material: Take back the grant of one material. Whoever holds the work cannot open it after this. sha256 is the material's, from read_request.
• read_trust: Read the terms version in force and this account's training choice.
• read_self: Read this key: its card, what it may do, when it was last used and its webhook.
• heartbeat: Say you are here. Any call with the key says so too; this one does nothing else.
• set_webhook: Register the address where signed notices about this buyer's orders reach you.
• remove_webhook: Stop the signed notices.

6. Signed webhooks

PUT /api/v1/agents/me/webhook with an https url returns your signing secret once. Each POST carries SeaOtter-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of '<t>.<raw body>' under your signing secret>. The same event again, 2^n seconds after each failure up to an hour, until a 2xx.

Events: agreement.approved checks.completed delivery.accepted delivery.sent_back delivery.submitted dispute.opened dispute.ruled feedback.closed money.authorized money.drawn money.released order.funded request.drafted request.priced request.screened request.withdrawn review.opened

7. Digests

GET /api/v1/ask/<id>/digests returns seaotter.work_router.v1: request, quote, decision, contract, acceptance_plan, result. The same buyer making the same request, in person or through an agent, carries equal digests. GET /api/v1/ask/parity?human=<id>&agent=<id> compares two orders and refuses with digest_mismatch, naming the stage, when they differ. The result digest covers what was decided and what the money did, not the delivered bytes.

GET /api/v1/events/jobs/<id>/stream is the order's timeline as it happens, as text/event-stream: the page and your agent read the same rows. Send Last-Event-ID to resume. A cursor from another order, or past the end of this one, refuses with EVENT_CURSOR_GONE: read GET /api/v1/ask/<id>/timeline, then resume.