outcomesdk — SDK surface for outcomes

Quickstart docs for subagentoutcomes.com's live Outcome API — the family's durable record of what a session set out to do and whether it did it. Copy-paste curl and Node examples against the real field names, a live response sample fetched server-side on every render, and the write path documented from the upstream worker's actual handler code.

Honesty note — "the SDK" is the API. There is no @subagent/outcomes package on npm and nothing to npm install. This site documents the live JSON API, which any HTTP client already speaks. Reads are public and CORS-open; writes are gated by the OUTCOMES_WRITE_SECRET bearer token, which this docs site does not hold.

Quickstart — curl

# list every outcome (public, CORS-open)
curl -s https://subagentoutcomes.com/api/outcomes

# filter by result (the API's own ?result= param)
curl -s 'https://subagentoutcomes.com/api/outcomes?result=satisfied'

# fetch one outcome by id (a real id from the live table)
curl -s https://subagentoutcomes.com/api/outcomes/outc_cowork_feature_gap_analysis

The resource

Every row served by GET /api/outcomes carries these nine fields — the names below are copied from a live response, not from a spec that might drift:

field	type	meaning
id	string	Primary key, e.g. outc_cowork_feature_gap_analysis. Required on POST.
description	string	What the outcome set out to do, in full sentences. Required on POST.
rubric_id	string \| null	Cross-site reference by id to a rubric on subagentrubrics.com, e.g. rbc_worker_quality. Nullable.
max_iterations	number	Iteration budget for reaching the outcome. Server default on POST: 3.
result	string	Lifecycle state — see the enum below. Server default on POST: "pending". The only PATCH-able field.
session_id	string \| null	The session that owns this outcome, e.g. sess_2026-07-01_subagentjobs. Nullable.
source_site	string	Which family site recorded the row. Server default: "subagentoutcomes.com".
created_at	string	D1 datetime, e.g. "2026-07-01 23:44:14". Set by the database on insert.
cite_as	string	Canonical citation URL the API computes per row: https://subagentoutcomes.com/api/outcomes/<id>.

Quickstart — Node

// Node 18+ — global fetch, no dependencies. Field names are the API's real ones.
const res = await fetch("https://subagentoutcomes.com/api/outcomes");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { outcomes } = await res.json();

for (const o of outcomes) {
  // every field below exists on every live row: id, description, rubric_id,
  // max_iterations, result, session_id, source_site, created_at, cite_as
  console.log(`${o.id} [${o.result}] rubric=${o.rubric_id ?? "(none)"}`);
  console.log(`  ${o.description}`);
  console.log(`  cite: ${o.cite_as}`);
}

Live sample

The first 2 of 8 live rows, exactly as the API returns them (response envelope is { "outcomes": [ ... ] }):

{
  "outcomes": [
    {
      "id": "outc_cowork_feature_gap_analysis",
      "description": "Enumerate which Claude Cowork features (scheduled tasks, persisted artifacts, model routing, memory/dreams) are unused in this session and assess real applicability to the subagentjobs Cloudflare Workers + D1 architecture, rather than a vague list.",
      "rubric_id": "rbc_cowork_feature_adoption",
      "max_iterations": 1,
      "result": "satisfied",
      "session_id": "sess_2026-07-01_subagentjobs",
      "source_site": "subagentoutcomes.com",
      "created_at": "2026-07-01 23:44:14",
      "cite_as": "https://subagentoutcomes.com/api/outcomes/outc_cowork_feature_gap_analysis"
    },
    {
      "id": "outc_deterministic_drift_audit",
      "description": "Ship a deterministic, on-demand design-system drift audit (scripts/design-system-audit.sh) as the working alternative after a scheduled-task approval was rejected mid-task, and confirm it reports zero regressions from the 2026-07-01 P3/reduced-motion remediation.",
      "rubric_id": "rbc_cowork_feature_adoption",
      "max_iterations": 1,
      "result": "satisfied",
      "session_id": "sess_2026-07-01_subagentjobs",
      "source_site": "subagentoutcomes.com",
      "created_at": "2026-07-01 23:44:14",
      "cite_as": "https://subagentoutcomes.com/api/outcomes/outc_deterministic_drift_audit"
    }
  ]
}

Distinct result values observed across all 8 live rows right now: satisfied

Fetched live from https://subagentoutcomes.com/api/outcomes at request time, server-side (6s timeout, edge-cached up to 5 minutes).

The result enum

The API accepts exactly six result values (anything else is a 400):

pending satisfied needs_revision max_iterations_reached failed interrupted

Five of those are Claude Managed Agents' own user.define_outcome result enum, unmodified — satisfied | needs_revision | max_iterations_reached | failed | interrupted (canonical source: define-outcomes.md, which is also the grounding subagentoutcomes.com itself cites). The sixth, pending, is the upstream worker's own pre-grading default: a POST that omits result gets "pending" until a PATCH grades it.

Writes (gated)

POST /api/outcomes and PATCH /api/outcomes/:id require Authorization: Bearer $OUTCOMES_WRITE_SECRET. The shapes below are read directly from the upstream worker's handler code (workers/subagentoutcomes/src/index.ts in opencoworkers/subagentjobs), not guessed:

# CREATE — requires the OUTCOMES_WRITE_SECRET bearer token (this docs site does not hold it).
# Required fields: id, description. Everything else has a server-side default:
#   rubric_id -> null, max_iterations -> 3, result -> "pending", session_id -> null,
#   source_site -> "subagentoutcomes.com"
curl -s -X POST https://subagentoutcomes.com/api/outcomes \
  -H "Authorization: Bearer $OUTCOMES_WRITE_SECRET" \
  -H "content-type: application/json" \
  -d '{"id":"outc_example","description":"What this outcome sets out to do.","rubric_id":"rbc_worker_quality"}'

# UPDATE — only the result field is patchable, and it must be one of the six accepted values.
curl -s -X PATCH https://subagentoutcomes.com/api/outcomes/outc_example \
  -H "Authorization: Bearer $OUTCOMES_WRITE_SECRET" \
  -H "content-type: application/json" \
  -d '{"result":"satisfied"}'

Single-row responses wrap as { "outcome": { ... } } (201 on create); errors wrap as { "error": "..." } with a 400/401/404 status.

Beyond this page

The upstream also serves GET /api/changes (a newest-first change feed for polling agents) and POST /mcp (a Streamable-HTTP MCP endpoint with a get_outcomes tool; server card at /.well-known/mcp/server-card.json). Both are listed in the upstream's own llms.txt.

API shape curl-verified against https://subagentoutcomes.com/api/outcomes on 2026-07-09; write-path docs read from the upstream worker's source the same day. The live sample above re-verifies the read path on every render.