DEVELOPERS — WIRE IT IN

From “I have an agent” to “every result is checked.”

One key is the whole handshake. Mint it below, point your runtime at the hosted MCP server or the HTTP API, and act on one result schema — score, band, flaws, upgrades.

INTEGRATION

Three ways in.

Everything routes to the same contract. The hosted API owns Ocean's typed prediction lifecycle and OtterScore's execution — conditioning, localization, rich returns, and the signed audit record. The MCP server and Python SDK are thin wrappers over that HTTP surface.

Get a key (no human)

Sign up autonomously — no console, no OAuth. One sk-otter key IS your identity: store it in your OS secret store, export OTTER_API_KEY, and reuse it for every check — never a per-task throwaway. A 429 means reuse the key you already have.

curl -s https://api.seaotter.ai/api/v1/agent-keys/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'
# -> { "api_key": "sk-otter-...", "free_quota": N, "next": { ... } }
# optional: register your identity (idempotent; auto-provisions on your first check anyway)
curl -s https://api.seaotter.ai/api/v1/identity/register \
  -H "Authorization: Bearer $OTTER_API_KEY" -X POST
# -> { "did": "did:web:seaotter.ai:id:agent-...", "handle": "...", "email": "...@agents.seaotter.ai" }

Hosted MCP — start here

MCP is the plug-in port your agent's runtime already speaks — Claude, Codex, Cursor, and friends. Paste this config and the tools appear; nothing to install, hosted by us. Check tools (otter_score, otter_iterate, otter_score_workflow) plus the workflow control plane (otter_fork_workflow, otter_workflow_plan, otter_evaluate_step, otter_resolve_workflow, otter_list_verticals, otter_workflow_archetypes).

{ "mcpServers": { "otterscore": {
    "url": "https://mcp.seaotter.ai/mcp",
    "headers": { "Authorization": "Bearer sk-otter-..." } } } }

curl

One-shot check over HTTP.

curl -s https://api.seaotter.ai/api/v1/eval/feedback \
  -H "Authorization: Bearer $OTTER_KEY" -H 'Content-Type: application/json' \
  -d '{ "modality":"text", "policy_id":"acme-prod-acceptance", "locale":"ja",
        "prompt":"Draft the Q3 incident postmortem",
        "artifact_parts":[{"mime_type":"text/plain","text":"..."}],
        "return_feedback_artifacts": true }'

Python SDK

Let the client drive produce → check → revise until ship.

from otterloop import OtterLoopClient
otter = OtterLoopClient(policy_id="acme-prod-acceptance", locale="ja")
final = otter.loop(produce=lambda feedback: my_agent.revise(feedback), work=my_agent.first_draft(), modality="document", references=["file://brand-guide.pdf", "file://gold-postmortem.md"], max_rounds=5, target_band="ship")

DEVELOPER CONSOLE

Get your API key

Mint an API key for your account, then copy a ready-to-paste MCP, Python SDK, or curl setup to wire any agent into SeaOtter. The secret is shown once — store it before you leave this page.

Loading keys…

AGENT QUICKSTART

Onboard an agent without a human in the loop after the first key.

SeaOtter is agent-native: an agent can discover this contract from /llms.txt, then run the whole loop over MCP or plain HTTP — no human in the loop. An agent can even mint its own free-tier key (POST /api/v1/agent-keys/signup), then predict, score, iterate, and govern workflows entirely on its own. Every call carries Authorization: Bearer <sk-otter-...>. Base: https://api.seaotter.ai. The same key drives both verbs: Ocean's typed lifecycle (register an exact state, predict bounded next states, select a route — see /docs/agent-native) and OtterScore's acceptance loop below.

1. Get a key — Self-serve, no human required: POST /api/v1/agent-keys/signup { "email":"agent@acme.com", "org_name":"acme" } provisions a free-tier account and returns an sk-otter key in one call. (A signed-in org user can also mint keys for an existing org via POST /api/v1/agent-keys.) The full sk-otter-<40 hex> secret is shown exactly once — hand it to the agent as the bearer token.
2. Connect (hosted MCP or HTTP) — Point your runtime at the hosted MCP server (https://mcp.seaotter.ai/mcp, Authorization: Bearer sk-otter-...) — no local install. You get the work-checking tools (otter_score, otter_iterate, otter_score_workflow, otter_list_policies, otter_get_feedback_artifact) plus the workflow control-plane tools (otter_fork_workflow, otter_workflow_plan, otter_evaluate_step, otter_resolve_workflow, otter_list_verticals, otter_workflow_archetypes). Or call the HTTP API directly.
3. Predict (Ocean) — Optional but the same protocol: register the exact state your agent is in (POST /api/v1/world-model/invocations), predict bounded next states (POST /api/v1/world-model/transitions/predict), and record one selected route. Predictions are advisory — authority stays predicted until real execution and evidence. Full walkthrough: /docs/agent-native.
4. Check (OtterScore) — POST /api/v1/eval/feedback with the artifact + the prompt the agent was given (+ optional policy_id, locale, references). Get back { run_id, verdict }. The verdict has score (0.0-1.0, where 1.0 = ship and lower = more flawed), band (ship / route_to_fix / quarantine / block), flaws[], upgrades[].
5. Read the flaws — Each flaw carries criterion, severity, evidence, detail, and an anchor (where: bbox / timestamp / cell / slide / page / span). upgrades[] are concrete fixes the agent can apply.
6. Iterate — Revise the work against the flaws, then POST /api/v1/eval/runs/{id}/iterate to re-score. Repeat until band clears your gate (e.g. ship). The Python SDK's otter.loop(produce=..., work=..., target_band="ship") drives this automatically.
7. Score a workflow (one-shot topology) — POST /api/v1/eval/workflows/{id}/topology to score an end-to-end multi-step workflow graph and get a composite + per-step + chain critique in a single call. Discover policies (GET /api/v1/eval/policies) and rubrics (GET /api/v1/eval/rubrics) to condition the check. Use this when you have the whole trajectory already and want one composite score.
8. Govern a running workflow (control plane) — For a complex multi-step workflow you are actively running, fork a vertical template (POST /api/v1/workflows/from-template), then loop plan -> evaluate per step: POST /api/v1/workflows/{id}/plan returns the next runnable steps; POST /api/v1/workflows/{id}/steps/{step}/evaluate checks each step and records { decision, score, visits }; routing.max_visits on a loop-back target bounds the iterate-on-fix loop; GET /api/v1/workflows/{id}/resolve returns the full per-step gate (bands, hard_rules, requirements, approval, retry, routing, policy_chain). Catalog: GET /api/v1/workflows/{templates,verticals,catalog,industries}. See the drop-in SDK in sdk/workflow/ and the guide at /docs/connect-workflow.

Machine-readable: /llms.txt · OpenAPI spec · interactive API docs.

1 — self-signup for a free-tier key (no human)

Returns a free-tier account + the full sk-otter-... secret exactly once.

curl -s -X POST https://api.seaotter.ai/api/v1/agent-keys/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"agent@acme.com","org_name":"acme"}'
# -> { "key": "sk-otter-...", "key_prefix": "sk-otter-abcde", ... }
# (existing org? a signed-in user can mint more keys:
#  POST /api/v1/agent-keys  -H 'Authorization: Bearer $SEAOTTER_USER_JWT'  -d '{"name":"my-agent"}')

2 — connect over the hosted MCP (.mcp.json)

Hosted, no install. Tools: otter_score · otter_iterate · otter_score_workflow · otter_list_policies · otter_get_feedback_artifact · otter_fork_workflow · otter_workflow_plan · otter_evaluate_step · otter_resolve_workflow · otter_list_verticals · otter_workflow_archetypes.

{ "mcpServers": { "otterscore": {
    "url": "https://mcp.seaotter.ai/mcp",
    "headers": { "Authorization": "Bearer sk-otter-..." } } } }

4 — score over HTTP

One-shot check -> verdict + run_id to keep iterating.

curl -s https://api.seaotter.ai/api/v1/eval/feedback \
  -H "Authorization: Bearer $OTTER_KEY" -H 'Content-Type: application/json' \
  -d '{ "modality":"text", "policy_id":"acme-prod-acceptance",
        "prompt":"Draft the Q3 incident postmortem",
        "artifact_parts":[{"mime_type":"text/plain","text":"...your work..."}],
        "return_feedback_artifacts": true }'
# -> { "run_id": "...", "verdict": { "score": ..., "band": "route_to_fix", "flaws": [...] } }

6 — iterate until it ships

Re-score a revision against the same run.

curl -s -X POST https://api.seaotter.ai/api/v1/eval/runs/$RUN_ID/iterate \
  -H "Authorization: Bearer $OTTER_KEY" -H 'Content-Type: application/json' \
  -d '{ "decision":"reprompt", "new_artifact_ref":"inline:v2",
        "artifact_parts":[{"mime_type":"text/plain","text":"...revised work..."}] }'

8 — govern a multi-step workflow (from-template -> plan -> evaluate)

Fork a vertical, ask plan for the next runnable steps, then evaluate each step. routing.max_visits on the loop-back target bounds the iterate-on-fix loop.

# fork a vertical workflow template
curl -s -X POST https://api.seaotter.ai/api/v1/workflows/from-template \
  -H "Authorization: Bearer $OTTER_KEY" -H 'Content-Type: application/json' \
  -d '{ "vertical":"support_ops", "new_id":"acme-tier1-triage" }'

# ask the plan for the next runnable steps
curl -s -X POST https://api.seaotter.ai/api/v1/workflows/acme-tier1-triage/plan \
  -H "Authorization: Bearer $OTTER_KEY" -H 'Content-Type: application/json' \
  -d '{ "completed": { "draft_reply": { "decision":"route_to_fix", "score":0.58, "visits":1 } } }'

# evaluate one step (check live or hand OtterScore a result)
curl -s -X POST https://api.seaotter.ai/api/v1/workflows/acme-tier1-triage/steps/draft_reply/evaluate \
  -H "Authorization: Bearer $OTTER_KEY" -H 'Content-Type: application/json' \
  -d '{ "grade_live": true, "artifact_text":"...revised reply..." }'
# -> { decision, score, visits }  ·  GET /api/v1/workflows/acme-tier1-triage/resolve for the full per-step gate

RESULT CONTRACT

The agent acts on one schema.

The result is designed for frontier agents, not screenshots of human review. It carries score, band, flaws, upgrades, anchors, rationale, and rich-feedback artifact refs the agent can use directly — those are the wire field names, unchanged.

Result schema

{
  "score": 0.91,
  "band": "ship",
  "decision": "ship",
  "flaws": [
    { "criterion": "source_grounding", "severity": "high", "evidence": "Unsupported number", "detail": "The claim is not backed by the cited file", "anchor": { "kind": "span", "span": [418, 462] } }
  ],
  "upgrades": [
    { "action": "Replace the unsupported figure", "target_criterion": "source_grounding", "draft": "Use the cited value from page 2 instead." }
  ],
  "rationale": "Localized feedback so the agent can revise the exact failing region.",
  "feedback_artifacts": [{ "kind": "annotated_png", "ref": "artifact://..." }]
}

CONDITIONING

The answer is conditional on your bar.

OtterLoop is not a generic "is this good" number. The contract can condition the result on your organisation's policy, the prompt or intent the agent was given, and the reference files it must obey.

Organisation policy

Apply the right acceptance policy so the same artifact can clear one team and fail another for a defensible reason.

Prompt and intent

Carry the original ask into the call so the work is read against the assignment, not against a generic idealized answer.

Reference files

Brand guides, gold examples, source-of-truth docs, and previous iterations all become conditioning evidence.

Anchors localize to bbox, point, span, cell, slide, page, or timestamp.
The band field is a runtime policy decision, not model prose pretending to be a gate.
Rich returns let the same result drive both human review and machine revision.

MODALITIES

Multimodal in. Rich multimodal out.

The same loop covers text, code, images, decks, documents, spreadsheets, audio, video, and multi-step trajectories. Returns can include both the canonical result JSON and media a human or agent can read.

Try the live demo Browse rubrics

MODALITIES	RETURNS
Image or design frame	Annotated PNG plus flaw bounding boxes and a markdown report
Deck, PDF, or document	Annotated pages, per-page notes, and machine-readable anchors
Spreadsheet	Flagged cells, criterion-grounded notes, and structured deltas
Video or audio	Timestamp markers, captions, and localized rationale
Text or code	Span-anchored review with upgrade drafts the agent can apply

SeaOtter

← All developer docs