Integration API reference

This reference covers the external integration interfaces supported by Kiwi. Use the endpoint shown by the signed-in app’s setup helper; the hosted service origin is not something to guess. Use the Kiwi app to manage accounts, invitations, project members, workflow publication, run decisions, and credentials.

Remote MCP

Connect an existing agent environment to the hosted Streamable HTTP MCP endpoint at /mcp. OAuth protected-resource metadata is available at /.well-known/oauth-protected-resource/mcp on the same host. The setup helper provides the full endpoint and selected project context. For OAuth setup, the client targets the exact /mcp resource and requests the user:org:read scope. A project-bound MCP key can be used by clients that support static Bearer authentication. See Remote MCP for authentication boundaries and the supported tool list.

Checker HTTP API

A project-bound checker credential can read the current verification context and report a named result for a run. It cannot manage project settings, submit ordinary workflow outputs, or make human decisions. The checker API uses the origin of the exact MCP URL copied from the signed-in Kiwi setup helper. Keep its scheme, host, and any port; remove only the /mcp path and append /v1/runs/{runId}/checks. For example, if the copied MCP URL is https://<host>:<port>/mcp, the checker request URL is https://<host>:<port>/v1/runs/{runId}/checks. Do not guess a host or use Kiwi’s website or documentation origin. This route is part of hosted Kiwi; customers do not deploy a separate service. MCP requests continue to use the full URL ending in /mcp.

Read the current context

Send a Bearer token:

GET /v1/runs/{runId}/checks
Authorization: Bearer YOUR_CHECKER_KEY

The response contains the current runVersion, acceptedPlanRevision, candidateRef, candidateRevision, implementationAttemptId, verificationAttemptId, verificationState, and the checks assigned to the credential under the accepted Plan. Read this context immediately before reporting; do not use a cached candidate or version.

Report a check

POST /v1/runs/{runId}/checks accepts these fields:

Field	Type	Meaning
command_id	UUID	Idempotency key for this report.
expected_run_version	positive integer	Current runVersion from the context read.
attempt_id	UUID	Current verificationAttemptId, or a new UUID when Verify is ready and none exists.
check_id	string	Exact assigned ID from checks[].checkId.
status	pass, fail, blocked, not-applicable	Observed result; only pass satisfies the required-check gate.
candidate_ref	string	Current candidateRef from the context read.
plan_revision	positive integer	Current acceptedPlanRevision.
implementation_attempt_id	UUID	Current implementationAttemptId.
evidence	object, optional	A summary and optional URL that support the observed result.

Example body for the customer task used across this guide:

{
  "command_id": "00000000-0000-4000-8000-000000000010",
  "expected_run_version": 2,
  "attempt_id": "00000000-0000-4000-8000-000000000011",
  "check_id": "help-search-results",
  "status": "pass",
  "candidate_ref": "commit:REPLACE_WITH_CURRENT_CANDIDATE",
  "plan_revision": 1,
  "implementation_attempt_id": "00000000-0000-4000-8000-000000000012",
  "evidence": {
    "summary": "The no-results message and revise-search action appear, and matching articles remain visible.",
    "url": "https://ci.example.org/runs/REPLACE_WITH_ACTUAL_RUN"
  }
}

Use only the current values from GET. If verificationAttemptId is null and Verify is ready, create one UUID for the first check report and use the returned attempt on later reports. Allowed statuses are pass, fail, blocked, and not-applicable. Only pass satisfies the gate. A successful POST returns a receipt and refreshed context. The receipt uses camelCase fields; the HTTP request uses snake_case. The response has this shape:

{
  "receipt": {
    "commandId": "00000000-0000-4000-8000-000000000010",
    "recorded": true,
    "replayed": false,
    "runVersion": 3,
    "eventCursor": 3,
    "eventId": "event_example",
    "eventType": "check_reported"
  },
  "checks": {
    "runId": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000001",
    "runVersion": 3,
    "verificationState": "in_progress",
    "acceptedPlanRevision": 1,
    "candidateRef": "commit:EXAMPLE_CANDIDATE",
    "candidateRevision": 1,
    "implementationAttemptId": "00000000-0000-4000-8000-000000000012",
    "verificationAttemptId": "00000000-0000-4000-8000-000000000011",
    "checks": [
      {
        "checkId": "help-search-results",
        "name": "Help search results QA",
        "expectedResult": "When a query has no matches, the help center explains that no results were found and offers a way to revise the search; matching results continue to display.",
        "status": "pass",
        "evidence": { "summary": "The no-results message and revise-search action appear, and matching articles remain visible." },
        "resultVersion": 3,
        "evidenceOrigin": "checker_reported",
        "reportedBy": "checker:EXAMPLE_KEY_ID"
      }
    ]
  }
}

These values are synthetic examples, not a real run or credential. See CI reporting for the full report sequence and Connections for credential handling.

Errors and retries

Integration errors return a JSON object with error and message. Common responses include 400 for invalid input, 401 for a missing or invalid credential, 403 for insufficient project or check authority, 404 for a missing run, 409 for stale state or a conflicting command replay, and 503 when an integration dependency is unavailable. MCP clients receive isError: true with an error and message in the text content. If a check POST may have reached Kiwi but its response is missing, retry the same command_id with the identical body. After a definitive stale response, read the context again and create a new command_id using the current version and attempt. See Retries and recovery.

Start

Use Kiwi

Connect agents and CI

Help

Integration API reference

Remote MCP

Checker HTTP API

Read the current context

Report a check

Errors and retries

​Remote MCP

​Checker HTTP API

​Read the current context

​Report a check

​Errors and retries

Remote MCP

Checker HTTP API

Read the current context

Report a check

Errors and retries