API & MCP documentation

Authentication

Both interfaces require an OAuth 2.0 bearer token. Supported scopes are projects_read and projects_write. Register public clients at POST /oauth/register; authorization-code and refresh-token grants are supported.

Authorization: Bearer <access_token>
Idempotency-Key: <optional-client-generated-key>
X-Request-ID: <optional-request-id>

OAuth discovery metadata is available at /.well-known/oauth-authorization-server. Protected-resource metadata is available for /api and /mcp.

HTTP API

All API endpoints are JSON endpoints under /api. Write operations require projects_write; read operations require projects_read.

POST /api/projects
POST /api/projects/:id/analyze
POST /api/projects/:id/evaluate_opportunities
GET  /api/projects/:project_id/opportunities
GET  /api/projects/:project_id/facts
POST /api/opportunities/:opportunity_id/runs
GET  /api/runs/:id
POST /api/runs/:id/cancel
GET  /api/runs/:run_id/handoffs
POST /api/runs/:run_id/steps/:id/retry
POST /api/handoffs/:id/resolve

MCP

Connect an MCP client to POST /mcp using Streamable HTTP. The server is stateless and exposes these tools:

Typical workflow

1. Create or list a project, then analyze it to refresh facts and opportunities.
2. Inspect an opportunity and start a run for an executable opportunity.
3. Call get_next_steps with the caller’s runtime capabilities.
4. Report the result with evidence, a failure, or a human handoff request.
5. Resolve handoffs, retry failed steps when appropriate, or cancel the run.

Runtime capabilities

Opportunity and Run payloads include execution_requirements. Inspect it before execution, configure the current runtime, and pass only currently available capabilities to get_next_steps. Missing capabilities return setup guidance in the structured error.

{
  "capabilities": {
    "browser": true,
    "http": true,
    "repo_read": false,
    "repo_write": false
  }
}

Browser execution

• Use a browser session the human can access and preserve it across authentication handoffs.
• Never request or expose passwords, session cookies, recovery codes, or secrets.
• Do not bypass CAPTCHA or MFA; request an otp_or_captcha handoff.
• Request approval before account creation, payment, or external publication.
• Verify the required receipt or public outcome instead of treating a click as success.

Reliability and errors

Use an idempotency key on retryable write operations. Responses include a request ID; structured errors include a code, message, optional details, and request ID. Runs cooperate with cancellation, and execution steps have server-enforced timeout deadlines.