Endpoint contract

Contract source and versioning

This reference and /openapi.json are generated from the same runtime contract registry. Contract tests verify that every published method maps to an implemented Next route. Schemas identify stable required fields while remaining open to additive response fields.

POST /responses

• Method: POST
• Path: $MC1_BASE_URL/responses
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project inference
• Implementation source: app/v1/responses/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/responses" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"colomboai/mc-1","input":"Summarize this incident."}'

POST /chat/completions

• Method: POST
• Path: $MC1_BASE_URL/chat/completions
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project inference
• Implementation source: app/v1/chat/completions/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/chat/completions" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"colomboai/mc-1","messages":[{"role":"user","content":"Summarize this incident."}]}'

POST /batches

• Method: POST
• Path: $MC1_BASE_URL/batches
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project inference
• Implementation source: app/v1/batches/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/batches" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"upstream_async","provider_id":"approved-provider","endpoint":"/v1/responses","completion_window":"24h","requests":[{"custom_id":"request-001","body":{"model":"approved-model","input":"Summarize this incident."}}]}'

GET /batches

• Method: GET
• Path: $MC1_BASE_URL/batches
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project inference
• Implementation source: app/v1/batches/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/batches" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /batches/{batchId}

• Method: GET
• Path: $MC1_BASE_URL/batches/{batchId}
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project inference
• Implementation source: app/v1/batches/[batchId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/batches/batchId" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /batches/{batchId}/cancel

• Method: POST
• Path: $MC1_BASE_URL/batches/{batchId}/cancel
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project inference
• Implementation source: app/v1/batches/[batchId]/cancel/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/batches/batchId/cancel" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json"

GET /batches/{batchId}/output

• Method: GET
• Path: $MC1_BASE_URL/batches/{batchId}/output
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project inference
• Implementation source: app/v1/batches/[batchId]/output/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/batches/batchId/output" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /rerank

• Method: POST
• Path: $MC1_BASE_URL/rerank
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project inference
• Implementation source: app/v1/rerank/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/rerank" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json"

GET /models

• Method: GET
• Path: $MC1_BASE_URL/models
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project catalog
• Implementation source: app/v1/models/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/models" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /models/capabilities

• Method: GET
• Path: $MC1_BASE_URL/models/capabilities
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project catalog
• Implementation source: app/v1/models/capabilities/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/models/capabilities" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /intelligence/execute

• Method: POST
• Path: $MC1_BASE_URL/intelligence/execute
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project intelligence
• Implementation source: app/v1/intelligence/execute/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/intelligence/execute" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":{"input":"Assess this change."},"objective":"balanced","constraints":{"max_cost_usd":0.05},"evaluation":{"required":true}}'

GET /routes/{routeId}

• Method: GET
• Path: $MC1_BASE_URL/routes/{routeId}
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Owning project route
• Implementation source: app/v1/routes/[routeId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/routes/routeId" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /routing

• Method: GET
• Path: $MC1_BASE_URL/routing
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project analytics
• Implementation source: app/v1/routing/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/routing" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /activity

• Method: GET
• Path: $MC1_BASE_URL/activity
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project analytics
• Implementation source: app/v1/activity/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/activity?limit=50" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /usage

• Method: GET
• Path: $MC1_BASE_URL/usage
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project finance
• Implementation source: app/v1/usage/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/usage" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /pricing

• Method: GET
• Path: $MC1_BASE_URL/pricing
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Authenticated catalog
• Implementation source: app/v1/pricing/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/pricing" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /billing

• Method: GET
• Path: $MC1_BASE_URL/billing
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project billing
• Implementation source: app/v1/billing/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/billing" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /billing/balance

• Method: GET
• Path: $MC1_BASE_URL/billing/balance
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project billing
• Implementation source: app/v1/billing/balance/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/billing/balance" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /billing/checkout

• Method: POST
• Path: $MC1_BASE_URL/billing/checkout
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project billing admin
• Implementation source: app/v1/billing/checkout/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/billing/checkout" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"credits","email":"[email protected]","amount_usd":25}'

GET /policies

• Method: GET
• Path: $MC1_BASE_URL/policies
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project policy
• Implementation source: app/v1/policies/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/policies" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /policies

• Method: POST
• Path: $MC1_BASE_URL/policies
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project policy admin
• Implementation source: app/v1/policies/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/policies" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Private project policy","rules":{"privacy":"private","max_cost_usd":0.05}}'

POST /policies/test

• Method: POST
• Path: $MC1_BASE_URL/policies/test
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project policy
• Implementation source: app/v1/policies/test/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/policies/test" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Classify this private workload.","objective":"balanced","max_cost_usd":0.05,"max_latency_ms":8000}'

GET /providers

• Method: GET
• Path: $MC1_BASE_URL/providers
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project catalog
• Implementation source: app/v1/providers/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/providers" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /providers/health

• Method: GET
• Path: $MC1_BASE_URL/providers/health
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project operations
• Implementation source: app/v1/providers/health/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/providers/health" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /benchmarks

• Method: GET
• Path: $MC1_BASE_URL/benchmarks
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project evaluation
• Implementation source: app/v1/benchmarks/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/benchmarks" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /api-keys

• Method: GET
• Path: $MC1_BASE_URL/api-keys
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/api-keys/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/api-keys" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /api-keys

• Method: POST
• Path: $MC1_BASE_URL/api-keys
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/api-keys/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/api-keys" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-service"}'

GET /app-setup

• Method: GET
• Path: $MC1_BASE_URL/app-setup
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project integration
• Implementation source: app/v1/app-setup/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/app-setup" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /app-setup

• Method: POST
• Path: $MC1_BASE_URL/app-setup
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/app-setup/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/app-setup" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing_mode":"smart","model_id":null,"products":["core","finops","everywhere"]}'

GET /byok

• Method: GET
• Path: $MC1_BASE_URL/byok
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/byok/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/byok" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /byok

• Method: POST
• Path: $MC1_BASE_URL/byok
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/byok/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/byok" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"approved-provider","endpoint":"https://provider.example/v1","secret_ref":"env:PROVIDER_API_KEY","region":"us","models":{"mc1-efficient":"approved-model"}}'

POST /byok/{providerId}

• Method: POST
• Path: $MC1_BASE_URL/byok/{providerId}
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/byok/[providerId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/byok/providerId" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json"

PATCH /byok/{providerId}

• Method: PATCH
• Path: $MC1_BASE_URL/byok/{providerId}
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/byok/[providerId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/byok/providerId" \
  -X PATCH \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_key":"REPLACEMENT_PROVIDER_KEY"}'

DELETE /byok/{providerId}

• Method: DELETE
• Path: $MC1_BASE_URL/byok/{providerId}
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/byok/[providerId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/byok/providerId" \
  -X DELETE \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json"

GET /provider-model-variants

• Method: GET
• Path: $MC1_BASE_URL/provider-model-variants
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage:read
• Implementation source: app/v1/provider-model-variants/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/provider-model-variants?limit=25&offset=0" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /provider-model-identities

• Method: GET
• Path: $MC1_BASE_URL/provider-model-identities
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage:read
• Implementation source: app/v1/provider-model-identities/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/provider-model-identities?limit=25&offset=0" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /connection-controls

• Method: GET
• Path: $MC1_BASE_URL/connection-controls
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/connection-controls/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/connection-controls" \
  -H "Authorization: Bearer $MC1_API_KEY"

PUT /connection-controls/{id}

• Method: PUT
• Path: $MC1_BASE_URL/connection-controls/{id}
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/connection-controls/[id]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/connection-controls/id" \
  -X PUT \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthly_limit_usd":25,"priority_bias":0}'

GET /provider-templates

• Method: GET
• Path: $MC1_BASE_URL/provider-templates
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage:read
• Implementation source: app/v1/provider-templates/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/provider-templates?limit=12&offset=0" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /provider-applications/{applicationId}

• Method: GET
• Path: $MC1_BASE_URL/provider-applications/{applicationId}
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/provider-applications/[applicationId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/provider-applications/applicationId" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /provider-applications/{applicationId}

• Method: POST
• Path: $MC1_BASE_URL/provider-applications/{applicationId}
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/provider-applications/[applicationId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/provider-applications/applicationId" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json"

POST /provider-applications/{applicationId}/compatibility-tests

• Method: POST
• Path: $MC1_BASE_URL/provider-applications/{applicationId}/compatibility-tests
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/provider-applications/[applicationId]/compatibility-tests/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/provider-applications/applicationId/compatibility-tests" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json"

GET /provider-applications

• Method: GET
• Path: $MC1_BASE_URL/provider-applications
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/provider-applications/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/provider-applications" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /provider-applications

• Method: POST
• Path: $MC1_BASE_URL/provider-applications
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/provider-applications/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/provider-applications" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example provider","contact_email":"[email protected]","documentation_url":"https://docs.example.com","api_endpoint":"https://provider.example/v1","protocol":"openai","model_ids":["example-model"]}'

GET /audit

• Method: GET
• Path: $MC1_BASE_URL/audit
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project security
• Implementation source: app/v1/audit/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/audit" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /forward/overview

• Method: GET
• Path: $MC1_BASE_URL/forward/overview
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward project
• Implementation source: app/v1/forward/overview/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/overview" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /forward/connectors

• Method: GET
• Path: $MC1_BASE_URL/forward/connectors
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward project
• Implementation source: app/v1/forward/connectors/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/connectors" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /forward/discovery

• Method: GET
• Path: $MC1_BASE_URL/forward/discovery
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward project
• Implementation source: app/v1/forward/discovery/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/discovery" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /forward/discovery

• Method: POST
• Path: $MC1_BASE_URL/forward/discovery
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization admin
• Implementation source: app/v1/forward/discovery/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/discovery" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Customer discovery","sources":["approved_connector_ref"]}'

POST /forward/discovery/{id}/execute

• Method: POST
• Path: $MC1_BASE_URL/forward/discovery/{id}/execute
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization admin
• Implementation source: app/v1/forward/discovery/[id]/execute/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/discovery/id/execute" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json"

GET /forward/deployments

• Method: GET
• Path: $MC1_BASE_URL/forward/deployments
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization reader
• Implementation source: app/v1/forward/deployments/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/deployments" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /forward/deployments

• Method: POST
• Path: $MC1_BASE_URL/forward/deployments
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in organization admin
• Implementation source: app/v1/forward/deployments/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/deployments" \
  -X POST \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"approval_id":"fwap_approved_release","target_id":"registered_staging"}'

POST /forward/deployments/recovery

• Method: POST
• Path: $MC1_BASE_URL/forward/deployments/recovery
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in organization admin
• Implementation source: app/v1/forward/deployments/recovery/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/deployments/recovery" \
  -X POST \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json"

GET /forward/jobs

• Method: GET
• Path: $MC1_BASE_URL/forward/jobs
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization reader
• Implementation source: app/v1/forward/jobs/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/jobs" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /forward/initiatives

• Method: GET
• Path: $MC1_BASE_URL/forward/initiatives
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization reader
• Implementation source: app/v1/forward/initiatives/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/initiatives" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /forward/initiatives

• Method: POST
• Path: $MC1_BASE_URL/forward/initiatives
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization admin
• Implementation source: app/v1/forward/initiatives/route.ts
• Required headers: Idempotency-Key: forward-request-001
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/initiatives" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: forward-request-001" \
  -d '{"title":"Invoice cycle time","owner_id":"user_01","business_problem":"Manual invoice review","acceptance_criteria":"Document baseline and compare observed cycle time"}'

GET /forward/initiatives/{id}

• Method: GET
• Path: $MC1_BASE_URL/forward/initiatives/{id}
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization reader
• Implementation source: app/v1/forward/initiatives/[id]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/initiatives/id" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /forward/initiatives/{id}/status

• Method: POST
• Path: $MC1_BASE_URL/forward/initiatives/{id}/status
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization admin
• Implementation source: app/v1/forward/initiatives/[id]/status/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/initiatives/id/status" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused","version":1,"reason":"Review scope before resuming work"}'

GET /forward/initiatives/{id}/artifacts

• Method: GET
• Path: $MC1_BASE_URL/forward/initiatives/{id}/artifacts
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization reader
• Implementation source: app/v1/forward/initiatives/[id]/artifacts/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/initiatives/id/artifacts" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /forward/initiatives/{id}/artifacts

• Method: POST
• Path: $MC1_BASE_URL/forward/initiatives/{id}/artifacts
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization admin
• Implementation source: app/v1/forward/initiatives/[id]/artifacts/route.ts
• Required headers: Idempotency-Key: forward-request-001
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/initiatives/id/artifacts" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: forward-request-001" \
  -d '{"stage":"Design","kind":"plan","summary":"Proposed change and rollback procedure","source":"Accountable owner review"}'

POST /forward/initiatives/{id}/approvals

• Method: POST
• Path: $MC1_BASE_URL/forward/initiatives/{id}/approvals
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Forward organization admin
• Implementation source: app/v1/forward/initiatives/[id]/approvals/route.ts
• Required headers: Idempotency-Key: forward-request-001
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/initiatives/id/approvals" \
  -X POST \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: forward-request-001" \
  -d '{"artifact_id":"fwa_01","action":"sandbox","environment":"staging","expires_at":1788825600000}'

POST /forward/approvals/{id}/review

• Method: POST
• Path: $MC1_BASE_URL/forward/approvals/{id}/review
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in human organization admin
• Implementation source: app/v1/forward/approvals/[id]/review/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/approvals/id/review" \
  -X POST \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"decision":"approve","reason":"Reviewed exact artifact and target scope"}'

GET /forward/initiatives/{id}/outcomes

• Method: GET
• Path: $MC1_BASE_URL/forward/initiatives/{id}/outcomes
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization reader
• Implementation source: app/v1/forward/initiatives/[id]/outcomes/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/initiatives/id/outcomes" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /forward/initiatives/{id}/outcomes/compare

• Method: GET
• Path: $MC1_BASE_URL/forward/initiatives/{id}/outcomes/compare
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization read
• Implementation source: app/v1/forward/initiatives/[id]/outcomes/compare/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/initiatives/id/outcomes/compare?baseline_id=fwout_baseline&observation_id=fwout_observation" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /forward/initiatives/{id}/outcomes

• Method: POST
• Path: $MC1_BASE_URL/forward/initiatives/{id}/outcomes
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization admin
• Implementation source: app/v1/forward/initiatives/[id]/outcomes/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/initiatives/id/outcomes" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metric":"invoice_cycle","unit":"hours","value":12,"observation_type":"baseline","source":"Customer report","method":"Median of 100 invoices","observed_at":1788735600000}'

POST /forward/discovery/{id}/enqueue

• Method: POST
• Path: $MC1_BASE_URL/forward/discovery/{id}/enqueue
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization admin
• Implementation source: app/v1/forward/discovery/[id]/enqueue/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/discovery/id/enqueue" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json"

POST /forward/jobs/dispatch

• Method: POST
• Path: $MC1_BASE_URL/forward/jobs/dispatch
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization forward:dispatch service key or admin
• Implementation source: app/v1/forward/jobs/dispatch/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/jobs/dispatch" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json"

POST /forward/jobs/{id}/cancel

• Method: POST
• Path: $MC1_BASE_URL/forward/jobs/{id}/cancel
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward organization admin
• Implementation source: app/v1/forward/jobs/[id]/cancel/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/jobs/id/cancel" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json"

GET /forward/graph

• Method: GET
• Path: $MC1_BASE_URL/forward/graph
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward project
• Implementation source: app/v1/forward/graph/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/graph" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /forward/opportunities

• Method: GET
• Path: $MC1_BASE_URL/forward/opportunities
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward project
• Implementation source: app/v1/forward/opportunities/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/opportunities" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /forward/opportunities/{opportunityId}/review

• Method: POST
• Path: $MC1_BASE_URL/forward/opportunities/{opportunityId}/review
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Forward project admin
• Implementation source: app/v1/forward/opportunities/[opportunityId]/review/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/forward/opportunities/opportunityId/review" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"opportunityId":"opportunity_01","status":"INVESTIGATING","reason":"Evidence requires accountable human investigation."}'

GET /advanced/capabilities

• Method: GET
• Path: $MC1_BASE_URL/advanced/capabilities
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project runtime
• Implementation source: app/v1/advanced/capabilities/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/advanced/capabilities" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /advanced/execute

• Method: POST
• Path: $MC1_BASE_URL/advanced/execute
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project runtime admin
• Implementation source: app/v1/advanced/execute/route.ts
• Required headers: Idempotency-Key: advanced-2026-08-30-01
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/advanced/execute" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: advanced-2026-08-30-01" \
  -d '{"mode":"agent_replanning","input":"Plan this bounded task.","max_latency_ms":10000}'

GET /training/jobs

• Method: GET
• Path: $MC1_BASE_URL/training/jobs
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project ML
• Implementation source: app/v1/training/jobs/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/training/jobs" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /training/jobs

• Method: POST
• Path: $MC1_BASE_URL/training/jobs
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project ML admin
• Implementation source: app/v1/training/jobs/route.ts
• Required headers: Idempotency-Key: training-2026-08-30-01
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/training/jobs" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: training-2026-08-30-01" \
  -d '{"dataset_id":"ds_authorized","provider_id":"provider_configured","base_model":"mc1-efficient","method":"lora","training_tokens":10000,"max_cost_usd":100}'

GET /specialized-models

• Method: GET
• Path: $MC1_BASE_URL/specialized-models
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project ML
• Implementation source: app/v1/specialized-models/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/specialized-models" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /team

• Method: GET
• Path: $MC1_BASE_URL/team
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Organization admin
• Implementation source: app/v1/team/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/team" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /trust/overview

• Method: GET
• Path: $MC1_BASE_URL/trust/overview
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage reader; MC1_TRUST_ENABLED
• Implementation source: app/v1/trust/overview/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/overview" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /trust/workload-grants

• Method: GET
• Path: $MC1_BASE_URL/trust/workload-grants
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in owner/admin; managed ingestion enabled
• Implementation source: app/v1/trust/workload-grants/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/workload-grants" \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT"

POST /trust/workload-grants

• Method: POST
• Path: $MC1_BASE_URL/trust/workload-grants
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in owner/admin; managed ingestion enabled
• Implementation source: app/v1/trust/workload-grants/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/workload-grants" \
  -X POST \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json"

DELETE /trust/workload-grants

• Method: DELETE
• Path: $MC1_BASE_URL/trust/workload-grants
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in owner/admin; managed ingestion enabled
• Implementation source: app/v1/trust/workload-grants/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/workload-grants" \
  -X DELETE \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json"

GET /trust/agents

• Method: GET
• Path: $MC1_BASE_URL/trust/agents
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage reader; MC1_TRUST_ENABLED
• Implementation source: app/v1/trust/agents/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /trust/agents

• Method: POST
• Path: $MC1_BASE_URL/trust/agents
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in project admin; MC1_TRUST_ENABLED
• Implementation source: app/v1/trust/agents/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents" \
  -X POST \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"Read-only support agent","owner_user_id":"user_01","capability_gate":1,"scope":{"environment":"production","data_class":"internal"},"policy":{"allowed_actions":["tool:read"]}}'

GET /trust/agents/{agentId}

• Method: GET
• Path: $MC1_BASE_URL/trust/agents/{agentId}
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage reader
• Implementation source: app/v1/trust/agents/[agentId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents/agentId" \
  -H "Authorization: Bearer $MC1_API_KEY"

PATCH /trust/agents/{agentId}

• Method: PATCH
• Path: $MC1_BASE_URL/trust/agents/{agentId}
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in project admin
• Implementation source: app/v1/trust/agents/[agentId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents/agentId" \
  -X PATCH \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"version":1,"policy":{"allowed_actions":["tool:read"]}}'

GET /trust/agents/{agentId}/evidence

• Method: GET
• Path: $MC1_BASE_URL/trust/agents/{agentId}/evidence
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage reader
• Implementation source: app/v1/trust/agents/[agentId]/evidence/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents/agentId/evidence" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /trust/agents/{agentId}/evidence

• Method: POST
• Path: $MC1_BASE_URL/trust/agents/{agentId}/evidence
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project admin
• Implementation source: app/v1/trust/agents/[agentId]/evidence/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents/agentId/evidence" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"control_id":"AATS-01","source":"approved-inventory","payload":{"system_id":"agent_01","test_result":"pass"},"observed_at":1789257600000,"expires_at":1789344000000}'

GET /trust/agents/{agentId}/evidence/{evidenceId}

• Method: GET
• Path: $MC1_BASE_URL/trust/agents/{agentId}/evidence/{evidenceId}
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in project admin
• Implementation source: app/v1/trust/agents/[agentId]/evidence/[evidenceId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents/agentId/evidence/evidenceId" \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT"

GET /trust/agents/{agentId}/assessments

• Method: GET
• Path: $MC1_BASE_URL/trust/agents/{agentId}/assessments
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage reader
• Implementation source: app/v1/trust/agents/[agentId]/assessments/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents/agentId/assessments" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /trust/agents/{agentId}/assessments

• Method: POST
• Path: $MC1_BASE_URL/trust/agents/{agentId}/assessments
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Configured independent signed-in evaluator; certification feature enabled
• Implementation source: app/v1/trust/agents/[agentId]/assessments/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents/agentId/assessments" \
  -X POST \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"decision":"approved","rationale":"Independent evaluator verified the complete scoped evidence set."}'

GET /trust/agents/{agentId}/status

• Method: GET
• Path: $MC1_BASE_URL/trust/agents/{agentId}/status
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage reader
• Implementation source: app/v1/trust/agents/[agentId]/status/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents/agentId/status" \
  -H "Authorization: Bearer $MC1_API_KEY"

GET /trust/agents/{agentId}/events

• Method: GET
• Path: $MC1_BASE_URL/trust/agents/{agentId}/events
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage reader
• Implementation source: app/v1/trust/agents/[agentId]/events/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents/agentId/events" \
  -H "Authorization: Bearer $MC1_API_KEY"

POST /trust/agents/{agentId}/state

• Method: POST
• Path: $MC1_BASE_URL/trust/agents/{agentId}/state
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in project admin
• Implementation source: app/v1/trust/agents/[agentId]/state/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/agents/agentId/state" \
  -X POST \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"status":"SUSPENDED","reason":"Containment after a critical control failure","version":2}'

POST /trust/decisions

• Method: POST
• Path: $MC1_BASE_URL/trust/decisions
• Auth: Bearer API key or authenticated MC-1 session, as enforced by the deployed route
• Scope: Project usage reader
• Implementation source: app/v1/trust/decisions/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/decisions" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"tagn_01","action":"tool:read"}'

GET /trust/registry/{certificateId}

• Method: GET
• Path: $MC1_BASE_URL/trust/registry/{certificateId}
• Auth: none; verify this public response against the canonical ColomboAI API origin
• Scope: Public
• Implementation source: app/v1/trust/registry/[certificateId]/route.ts
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 404 scoped_resource — verify the identifier belongs to the authenticated project
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/trust/registry/certificateId" \
  -H "Accept: application/json"

POST /support/requests

• Method: POST
• Path: $MC1_BASE_URL/support/requests
• Auth: authenticated MC-1 site session with verified user email; bearer-only API keys are rejected
• Scope: Signed-in project
• Implementation source: app/v1/support/requests/route.ts
• Required headers: Idempotency-Key: support-2026-08-30-01
• Errors: structured endpoint-safe failures are listed below
• Error: 401 authentication — replace or re-scope the bearer key; do not retry unchanged
• Error: 403 authorization_or_policy — inspect project authority and the governing rule; do not bypass
• Error: 400 invalid_request — correct the named field; do not retry unchanged
• Error: 409 state_conflict — reconcile idempotency or current resource state before retrying
• Error: 429 rate_limited — wait for Retry-After when present and retry only idempotent work
• Error: 5xx service_or_upstream — use bounded backoff only when the operation is safe to repeat
• Rate limits: organization, project, model, and provider boundaries are deployment- and plan-specific; honor 429 and Retry-After without blind retries

curl "$MC1_BASE_URL/support/requests" \
  -X POST \
  -H "Cookie: $CAIRO_JWT_COOKIE_NAME=$CAIRO_JWT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: support-2026-08-30-01" \
  -d '{"category":"technical","priority":"normal","subject":"Request failed","message":"Include a safe route ID and timestamp."}'