> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwiflow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration API reference

> Supported remote MCP and checker HTTP contracts for connecting customer agents and CI to hosted Kiwi.

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](https://docs.kiwiflow.io/remote-mcp.md) 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:

```http theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://docs.kiwiflow.io/ci-reporting.md) for the full report sequence and [Connections](https://docs.kiwiflow.io/connections.md) 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](https://docs.kiwiflow.io/retries-and-recovery.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.