Agents & API

Keep one board per product, named after the product. Create each candidate's release review inside that board. This keeps features, supporting systems, and review history together.

Connect the coding agent already working on your project. It reads the repository and existing board, maps capabilities to their implementation, defines checks, and submits results from real verification. People review the release conclusion, gaps, and decisions instead of entering every record by hand.

StateBoard 2026.10.0 exposes ordinary release maintenance through REST and the built-in MCP server at /api/mcp. The tools cover product context, capabilities, dependencies, release scope, versioned checks, and evidence, alongside the existing visual board tools. A current human owner records release decisions and controls curated release publication.

StateBoard does not host an LLM, execute tests, poll repositories, or fetch evidence URLs. The connected agent or CI does that work within its own environment and permissions, then pushes records to your instance. Both StateBoard surfaces work without a third-party service or new runtime network access; an external agent's own hosting requirements are separate.

Create a key

Sign in through your configured OIDC provider, then open your avatar menu → API keys (/settings/api-keys). Name the key, select its role, and copy the secret — it is shown exactly once. Keys look like sbk_…; only a hash is stored server-side.

• Use an editor key for an agent that maintains the product and appends evidence. A viewer key supports read-only assessment.
• A key acts as its creator, capped at the lower of its assigned role and the creator's current role. Demotion or removal restricts the key too.
• Keys expire after 90 days by default. You can choose 30/60/90 days, a year, or explicitly no expiration. Via the key API, expiresInDays accepts a number or null.
• Creation and revocation require a browser session. Owners can inventory and revoke every key in the workspace.
• Writes are audited. Evidence retains member, source, and credential attribution; a supplied result is not a guarantee that its claim is true.

Keep the secret in the agent's environment or CI secret store, never in the repository. Even an owner-scoped API key cannot record a release decision or publish/revoke a release review.

Connect and teach the workflow

Point an MCP client at https://your-instance/api/mcp with the key as a bearer token. For example, with the URL and secret in environment variables:

claude mcp add --transport http stateboard "$STATEBOARD_URL/api/mcp" \
  --header "Authorization: Bearer $STATEBOARD_API_KEY"

npx skills@latest add saschb2b/stateboard

The packaged StateBoard skill teaches repository reconciliation, exact-candidate evidence, revision conflicts, and visual status semantics. Use the skill from your deployed version when pinning a release. MCP describes its available tools and fields at connection time.

A useful initial request is:

Set up StateBoard for this project. Inspect the existing board and repository, reuse its capabilities and components, map the critical outcomes and their dependencies, and assess this candidate for our agreed release context. Run the relevant checks and record their actual results. Leave unsupported claims visible and return the assessment for review.

Give the agent the intended target environment, audience, configuration, and any release requirements that are not discoverable from the project. It can infer grounded implementation details and maintain them without field-by-field approval. When a material requirement is genuinely unknown, it should surface that question rather than invent an answer.

How maintenance works

1. Read before writing. list_boards finds the product; get_product returns its capabilities, components, declared relationships, regions, and assessments. Reuse existing IDs instead of creating a new catalog on every run.
2. Reconcile the change. Inspect source, interfaces, tests, and deployment configuration. Update affected outcomes and wiring, with concise references explaining the basis for each relationship. Declared architecture is context, not verified runtime behavior. Dependencies upsert by consumer ID, provider ID, and exact relation text. Preserve the relation for description-only updates and retries; a deliberate semantic replacement creates a new edge and deletes the obsolete edge by ID.
3. Assess an exact candidate. Reuse a matching assessment or create one for the immutable candidate, validation and target environments, audience, and configuration. create_release starts with no checks. Reconcile all still-applicable prior capability, component, and release requirements into new check IDs, preserving required status, claim, method, environment, and freshness where applicable. Explain changes for the new scope/context, include each capability's required functional acceptance check, and copy no evidence.
4. Verify and append. Run actual checks in the agent's development or CI environment. Submit pass, fail, or inconclusive observations tied to that check revision and exact context. Unattempted claims remain missing. Builds, source inspection, and simulated reviewers do not establish unrelated outcomes or human approval.
5. Read the conclusion. Fetch readiness and return the authenticated assessment link with blockers, missing verification, and accountable owners. A human owner reviews and records the decision.

For ongoing use, ask the coding agent to update the affected StateBoard records when it completes a change, or add evidence submission to an existing CI run. These are bounded updates using the same records. Connecting MCP alone does not install a scheduler or start a background agent. A new candidate gets a new assessment; old observations remain with the candidate they verified.

MCP tools

The endpoint is stateless Streamable HTTP: one JSON response per call, without SSE or MCP sessions. Discover the exact schemas from the connected instance.

Product mutations use board_id and, where applicable, a top-level capability_id, component_id, or dependency_id. Release mutations use release_id, top-level expected_revision, and check_id for check edits. New or changed fields go in a nested data object using the REST field names in camelCase. Capability updates also include the current definitionRevision in data.

For example, create_check takes:

{
  "release_id": "RELEASE_ID",
  "expected_revision": 3,
  "data": {
    "subjectType": "capability",
    "subjectId": "CAPABILITY_ID",
    "claim": "An authorized reviewer can inspect the candidate and identify its missing required evidence.",
    "category": "functional",
    "required": true,
    "ownerLabel": "Product team",
    "method": "Exercise the release overview with a candidate containing a missing required result.",
    "environment": "local-development",
    "maxAgeMs": 86400000
  }
}

Replace the IDs, revision, owner, and environment with the actual assessment's values. A successful product write returns refreshed product context. A release write returns the updated workspace, including assessment.revision and calculated readiness. Results are available as JSON text and under structuredContent.data. Release tool errors set isError and include structuredContent.error with a code and message.

Use the returned revision for the next release write; refresh after shared product edits because changes to wiring can advance affected assessment revisions. On conflict, fetch the current workspace and reconcile before retrying. Do not blindly repeat a stale edit, overwrite changed acceptance criteria, or weaken a failed gate to obtain a ready result. Creates are not universally idempotent. If the outcome is unknown, re-read and reconcile matching records rather than blindly retrying; surface ambiguous concurrent duplicates instead of choosing one without a basis.

REST and file uploads

The same bearer key works on visual and release editing routes. REST returns resources directly and errors as { "error": "…" }. Useful entry points are:

curl -H "Authorization: Bearer $STATEBOARD_API_KEY" \
  "$STATEBOARD_URL/api/releases/RELEASE_ID"

curl -X POST -H "Authorization: Bearer $STATEBOARD_API_KEY" \
  -H "Content-Type: application/json" --data-binary @evidence.json \
  "$STATEBOARD_URL/api/releases/RELEASE_ID/evidence"

The release readiness guide gives the complete evidence payload. MCP's submit_evidence uses the same fields inside data, with expected_revision at the top level instead of REST's expectedRevision.

Screenshots and private release assets use multipart REST uploads rather than MCP image arguments:

• POST /api/boards/BOARD_ID/screens, with file and label, creates a visual screen. PNG/JPEG/WebP/GIF, up to 25 MB. These legacy board images are public visual content.
• POST /api/releases/RELEASE_ID/assets uploads a confidential release image through authenticated storage.

Region coordinates x, y, w, h are normalized fractions in [0, 1], never pixels. Visual shipped means working in production; local/staging checks do not set it automatically. mock and missing keep their existing meanings. Evidence belongs in check records, even when a short region note also explains the visual status.

Evidence, conflicts, and boundaries

Pin and preserve the exact source snapshot, built artifact, or manifest and relevant configuration before running verification. Dirty-worktree results cannot use the base commit or HEAD as their tested identity. If that snapshot was not preserved, rerun against a pinned candidate; retain and report earlier failure logs as unattributed observations without fabricating evidence or requiring a commit.

Evidence must identify the active check revision and exact candidate, expected environment, audience, and configuration. observedAt is the actual verification time in Unix milliseconds, not the upload time. Use a stable event identity and retain the source/run reference. A source-derived mapping or passing supporting test cannot verify a broader capability by itself.

Retry an uncertain submission with the same event identity and identical payload. That returns the original observation even if the assessment revision has since advanced. Reusing the identity for changed data conflicts. For a new event with a stale revision, refresh and review the definitions before retrying; an old observation may no longer verify the changed claim. A failed or inconclusive result remains part of the evidence history.

API keys are denied at POST /api/releases/RELEASE_ID/decisions, POST /api/releases/RELEASE_ID/share-links, and DELETE /api/release-share-links/TOKEN. A current owner uses a signed-in browser for those actions. Session-authenticated release mutations also require the deployment's matching request origin. Visual board sharing through MCP does not publish the private release assessment.