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?model=colomboai%2Fmc-1&input=Summarize+this+incident." \
  -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?model=colomboai%2Fmc-1&messages=%5Bobject+Object%5D" \
  -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."}]}'

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?task=%5Bobject+Object%5D&objective=balanced&constraints=%5Bobject+Object%5D&evaluation=%5Bobject+Object%5D" \
  -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?mode=credits&email=billing-owner%40example.com&amount_usd=25" \
  -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?name=Private+project+policy&rules=%5Bobject+Object%5D" \
  -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?prompt=Classify+this+private+workload.&objective=balanced&max_cost_usd=0.05&max_latency_ms=8000" \
  -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?name=production-service" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-service"}'

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?name=approved-provider&endpoint=https%3A%2F%2Fprovider.example%2Fv1&secret_ref=env%3APROVIDER_API_KEY&region=us" \
  -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"}'

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 project 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?name=Customer+discovery&sources=approved_connector_ref" \
  -X POST \
  -H "Authorization: Bearer $MC1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Customer discovery","sources":["approved_connector_ref"]}'

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/opportunity_01/review?status=INVESTIGATING&reason=Evidence+requires+accountable+human+investigation." \
  -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?mode=agent_replanning&input=Plan+this+bounded+task.&max_latency_ms=10000" \
  -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?dataset_id=ds_authorized&provider_id=provider_configured&base_model=mc1-efficient&method=lora&training_tokens=10000&max_cost_usd=100" \
  -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"

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?category=technical&priority=normal&subject=Request+failed&message=Include+a+safe+route+ID+and+timestamp." \
  -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."}'