API reference

GET /api/v1/outcomes

list_outcomes — List outcomes with progress, verified counts and status.

Permission: outcomes:read · MCP tool

Field	Type	Required	Notes
filter	string	no	all | active | achieved | at_risk | failed default "all"
workspace_id	string	no

curl -X GET "https://outcomeos.cloud/api/v1/outcomes" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden validation

GET /api/v1/outcomes/:id

get_outcome — Get one outcome: success criteria, verification config, progress and linked workflows.

Permission: outcomes:read · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/outcomes/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

POST /api/v1/outcomes

create_outcome — Create a business outcome with explicit success criteria and a verification method.

An outcome is achieved only when verified events satisfy its success criteria — never because a workflow completed.

Permission: outcomes:write · MCP tool

Field	Type	Required	Notes
workspace_id	string	no
name	string	yes
description	string	no	default ""
category	string	yes	lead_response | payment_recovery | customer_onboarding | appointment_booking | sales_followup | support_resolution | custom
priority	string	no	low | medium | high | critical default "medium"
success_criteria	object	yes
verification_config	object	no	default {"trusted_sources":["api","signed_webhook","integration"],"at_risk_threshold":0.2}
execution_strategy	string	no	default ""
deadline	union	no
required_integrations	array	no	default []
activate	boolean	no	default true

curl -X POST "https://outcomeos.cloud/api/v1/outcomes" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Reply to every qualified lead within 5 minutes","category":"lead_response","success_criteria":{"subject_label":"lead","start_event":"lead.received","required_events":[{"event_type":"customer.reply_received"}],"subject_deadline_seconds":300,"target_metric":"Leads replied","target_value":100}}'

Errors: unauthorized forbidden validation not_found

PATCH /api/v1/outcomes/:id

update_outcome — Update an outcome's definition, or cancel / reactivate it (status: cancelled | not_started).

Permission: outcomes:write · MCP tool

Field	Type	Required	Notes
workspace_id	string	no
name	string	no
description	string	no	default ""
category	string	no	lead_response | payment_recovery | customer_onboarding | appointment_booking | sales_followup | support_resolution | custom
priority	string	no	low | medium | high | critical default "medium"
success_criteria	object	no
verification_config	object	no	default {"trusted_sources":["api","signed_webhook","integration"],"at_risk_threshold":0.2}
execution_strategy	string	no	default ""
deadline	union	no
required_integrations	array	no	default []
activate	boolean	no	default true
status	string	no	not_started | cancelled

curl -X PATCH "https://outcomeos.cloud/api/v1/outcomes/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden validation not_found

DELETE /api/v1/outcomes/:iddestructive

delete_outcome — Delete an outcome and its events. Linked workflows are kept and unlinked.

Permission: outcomes:write · MCP tool

curl -X DELETE "https://outcomeos.cloud/api/v1/outcomes/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

GET /api/v1/outcomes/:id/events

list_outcome_events — List the latest events recorded for an outcome, with whether each was counted as verified.

Permission: outcomes:read · MCP tool

Field	Type	Required	Notes
limit	integer	no	default 200

curl -X GET "https://outcomeos.cloud/api/v1/outcomes/<id>/events" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

GET /api/v1/outcomes/:id/subjects

list_outcome_subjects — List evaluated subjects (e.g. leads, invoices) with achieved / failed / pending status and reason.

Permission: outcomes:read · MCP tool

Field	Type	Required	Notes
status	string	no	pending | achieved | failed
limit	integer	no	default 200

curl -X GET "https://outcomeos.cloud/api/v1/outcomes/<id>/subjects" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

POST /api/v1/outcomes/:id/events

ingest_outcome_event — Record an outcome event (e.g. customer.reply_received for a lead). Counted only if its source is trusted by the outcome.

Events sent with an API key have source `api`; events added from the dashboard have source `manual`. Both are recorded; whether they count is decided by the outcome's verification config. Send `idempotency_key` to make retries safe. Matching `wait_for_event` steps resume automatically.

Permission: outcome_events:write · MCP tool

Field	Type	Required	Notes
event_type	string	yes
subject_id	string	no
data	object	no	default {}
idempotency_key	string	no
occurred_at	string	no

curl -X POST "https://outcomeos.cloud/api/v1/outcomes/<id>/events" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"customer.reply_received","subject_id":"lead_123","data":{"channel":"whatsapp"},"idempotency_key":"msg_abc"}'

Errors: unauthorized forbidden validation not_found

POST /api/v1/outcomes/:id/ingest-secret

reveal_outcome_ingest_secret — Reveal (or rotate) the HMAC secret for the outcome's signed event webhook.

Permission: outcomes:write · not exposed over MCP

Field	Type	Required	Notes
rotate	boolean	no	default false

curl -X POST "https://outcomeos.cloud/api/v1/outcomes/<id>/ingest-secret" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found

GET /api/v1/workflows

list_workflows — List workflows with trigger, linked outcome, status, executions and success rate.

Permission: workflows:read · MCP tool

Field	Type	Required	Notes
workspace_id	string	no
outcome_id	string	no

curl -X GET "https://outcomeos.cloud/api/v1/workflows" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

POST /api/v1/workflows/validate

validate_workflow — Validate a workflow definition without saving it.

Permission: workflows:read · MCP tool

Field	Type	Required	Notes
definition	object	yes

curl -X POST "https://outcomeos.cloud/api/v1/workflows/validate" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden

GET /api/v1/workflows/:id

get_workflow — Get a workflow: draft definition, webhook URL and version history.

Permission: workflows:read · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/workflows/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

POST /api/v1/workflows

create_workflow — Create a draft workflow, empty, from a template id, or from a JSON definition.

Permission: workflows:write · MCP tool

Field	Type	Required	Notes
workspace_id	string	no
name	string	yes
description	string	no	default ""
outcome_id	string,null	no
definition	object	no
template_id	string	no

curl -X POST "https://outcomeos.cloud/api/v1/workflows" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Lead webhook to CRM","template_id":"webhook_to_http"}'

Errors: unauthorized forbidden validation not_found

PATCH /api/v1/workflows/:id

update_workflow — Save the draft (name, description, linked outcome, definition). Returns validation issues; publishing requires none.

Permission: workflows:write · MCP tool

Field	Type	Required	Notes
name	string	no
description	string	no
outcome_id	string,null	no
definition	object	no

curl -X PATCH "https://outcomeos.cloud/api/v1/workflows/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden validation not_found

POST /api/v1/workflows/:id/publish

publish_workflow — Publish the draft as a new immutable version. Running executions keep the version they started with.

Permission: workflows:publish · MCP tool

curl -X POST "https://outcomeos.cloud/api/v1/workflows/<id>/publish" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden validation not_found plan_limit conflict

POST /api/v1/workflows/:id/status

set_workflow_status — Activate or deactivate a published workflow. Inactive workflows reject webhook triggers.

Permission: workflows:publish · MCP tool

Field	Type	Required	Notes
status	string	yes	active | inactive

curl -X POST "https://outcomeos.cloud/api/v1/workflows/<id>/status" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found plan_limit conflict

POST /api/v1/workflows/:id/duplicate

duplicate_workflow — Copy a workflow's draft into a new draft workflow.

Permission: workflows:write · MCP tool

curl -X POST "https://outcomeos.cloud/api/v1/workflows/<id>/duplicate" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found

DELETE /api/v1/workflows/:iddestructive

delete_workflow — Delete a workflow, its versions and execution history.

Permission: workflows:delete · MCP tool

curl -X DELETE "https://outcomeos.cloud/api/v1/workflows/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

POST /api/v1/workflows/:id/testdestructive

test_workflow — Run the current draft once with a sample payload. Test runs never record outcome events.

HTTP and connector steps do run for real during a test, because a fake success would hide real failures.

Permission: executions:run · MCP tool

Field	Type	Required	Notes
payload	object	no	default {}

curl -X POST "https://outcomeos.cloud/api/v1/workflows/<id>/test" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden validation not_found plan_limit

POST /api/v1/workflows/:id/rundestructive

run_workflow — Start an execution of the published version with a JSON payload (same as the webhook trigger, authenticated by API key).

Send idempotency_key to make retries safe: a repeated key returns the original execution instead of starting a new one.

Permission: executions:run · MCP tool

Field	Type	Required	Notes
payload	object	no	default {}
idempotency_key	string	no

curl -X POST "https://outcomeos.cloud/api/v1/workflows/<id>/run" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"lead_id":"lead_123","qualified":true},"idempotency_key":"evt_001"}'

Errors: unauthorized forbidden validation not_found plan_limit conflict

GET /api/v1/workflows/:id/versions/:version

get_workflow_version — Get the immutable definition of a published version.

Permission: workflows:read · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/workflows/<id>/versions/<version>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

POST /api/v1/workflows/:id/webhook-secret

reveal_webhook_secret — Reveal (or rotate) the workflow's webhook signing secret.

Permission: workflows:publish · not exposed over MCP

Field	Type	Required	Notes
rotate	boolean	no	default false

curl -X POST "https://outcomeos.cloud/api/v1/workflows/<id>/webhook-secret" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found

GET /api/v1/executions

list_executions — List executions, newest first. Filter by status (use `attention` for failed + requires_attention), workflow or outcome.

Permission: executions:read · MCP tool

Field	Type	Required	Notes
status	string	no	pending | running | waiting | completed | failed | cancelled | requires_attention | attention
workflow_id	string	no
outcome_id	string	no
limit	integer	no	default 50
cursor	string	no

curl -X GET "https://outcomeos.cloud/api/v1/executions" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden validation

GET /api/v1/executions/:id

get_execution — Get an execution's full step timeline: inputs, outputs, errors, retries, logs (secrets masked) and related outcome events.

Permission: executions:read · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/executions/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

POST /api/v1/executions/:id/replaydestructive

replay_execution — Replay a failed, cancelled or attention-required execution. Default mode reuses steps that already succeeded and re-runs from the failure.

mode=from_failure (default) copies successful step outputs from the original and re-runs only what failed or never ran, using the same step idempotency keys. mode=full re-runs every step and requires confirm_full=true because non-idempotent actions (messages, payments) may repeat. Ask the user before calling this tool.

Permission: executions:replay · MCP tool

Field	Type	Required	Notes
mode	string	no	from_failure | full default "from_failure"
confirm_full	boolean	no

curl -X POST "https://outcomeos.cloud/api/v1/executions/<id>/replay" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found conflict plan_limit validation

POST /api/v1/executions/:id/canceldestructive

cancel_execution — Cancel a pending, running or waiting execution. Steps already in flight finish; nothing new starts.

Permission: executions:cancel · MCP tool

curl -X POST "https://outcomeos.cloud/api/v1/executions/<id>/cancel" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found conflict

GET /api/v1/integrations/catalog

list_integration_catalog — List every integration with its real availability: available, beta, needs operator setup, or coming soon.

Permission: integrations:read · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/integrations/catalog" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

GET /api/v1/integrations

list_connections — List connections. Credentials are never returned; only which secret fields are set.

Permission: integrations:read · MCP tool

Field	Type	Required	Notes
provider	string	no

curl -X GET "https://outcomeos.cloud/api/v1/integrations" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

POST /api/v1/integrations

create_connection — Save a connection (status pending). It only becomes connected after test_connection succeeds against the real provider.

Permission: integrations:manage · MCP tool

Field	Type	Required	Notes
provider	string	yes
connection_name	string	yes
credentials	object	no	default {}

curl -X POST "https://outcomeos.cloud/api/v1/integrations" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"http","connection_name":"CRM API","credentials":{"base_url":"https://api.example.com","auth_type":"bearer","token":"…","test_path":"/health"}}'

Errors: unauthorized forbidden validation conflict

PATCH /api/v1/integrations/:id

update_connection — Update a connection's name or credentials. Changing credentials resets it to pending until tested again. Blank secret fields keep the stored value.

Permission: integrations:manage · MCP tool

Field	Type	Required	Notes
connection_name	string	no
credentials	object	no

curl -X PATCH "https://outcomeos.cloud/api/v1/integrations/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found validation conflict

POST /api/v1/integrations/:id/test

test_connection — Verify a connection against the real provider. Marks it connected only on success; otherwise records the provider's error.

Permission: integrations:manage · MCP tool

curl -X POST "https://outcomeos.cloud/api/v1/integrations/<id>/test" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found plan_limit

DELETE /api/v1/integrations/:iddestructive

delete_connection — Delete a connection and its encrypted credentials. Workflow steps using it will fail with needs_credentials.

Permission: integrations:manage · MCP tool

curl -X DELETE "https://outcomeos.cloud/api/v1/integrations/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

POST /api/v1/marketplace/connectors

submit_community_connector — Submit (or resubmit) a declarative community connector for review. Once approved it is listed in the marketplace and anyone can connect it. A resubmission goes back to review while the approved version stays live.

Permission: integrations:manage · MCP tool

Field	Type	Required	Notes
manifest	object	yes

curl -X POST "https://outcomeos.cloud/api/v1/marketplace/connectors" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden validation conflict

GET /api/v1/marketplace/connectors

list_my_community_connectors — List community connectors your organization has submitted, with review status and reviewer notes.

Permission: integrations:read · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/marketplace/connectors" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

GET /api/v1/marketplace/review

list_connector_review_queue — Platform admins only: community connector submissions, pending first.

Permission: integrations:read · not exposed over MCP

Field	Type	Required	Notes
status	string	no	pending | approved | rejected | all default "pending"

curl -X GET "https://outcomeos.cloud/api/v1/marketplace/review" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

POST /api/v1/marketplace/review/:id

review_community_connector — Platform admins only: approve (publish the submitted version), reject, or unpublish a community connector. The submitter is emailed.

Permission: integrations:read · not exposed over MCP

Field	Type	Required	Notes
decision	string	yes	approve | reject | unpublish
updated_at	string	yes
note	string	no

curl -X POST "https://outcomeos.cloud/api/v1/marketplace/review/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found conflict validation

GET /api/v1/org

get_organization — Get the active organization: plan, limits, usage, workspaces and your role.

Permission: org:read · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/org" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

PATCH /api/v1/org

update_organization — Rename the organization.

Permission: org:update · MCP tool

Field	Type	Required	Notes
name	string	yes

curl -X PATCH "https://outcomeos.cloud/api/v1/org" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden validation

POST /api/v1/org/workspaces

create_workspace — Create a workspace inside the organization.

Permission: org:update · MCP tool

Field	Type	Required	Notes
name	string	yes

curl -X POST "https://outcomeos.cloud/api/v1/org/workspaces" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden validation conflict plan_limit

GET /api/v1/audit-logs

list_audit_logs — List audit log entries for the organization, newest first.

Permission: audit:read · MCP tool

Field	Type	Required	Notes
limit	integer	no	default 100
before	string	no
resource_type	string	no

curl -X GET "https://outcomeos.cloud/api/v1/audit-logs" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

GET /api/v1/org/members

list_members — List organization members and their roles.

Permission: team:read · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/org/members" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

PATCH /api/v1/org/members/:id

update_member_role — Change a member's role (admin, editor, viewer).

Permission: team:manage · MCP tool

Field	Type	Required	Notes
role	string	yes	admin | editor | viewer

curl -X PATCH "https://outcomeos.cloud/api/v1/org/members/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found

DELETE /api/v1/org/members/:iddestructive

remove_member — Remove a member from the organization. Their API keys for this org are revoked.

Permission: team:manage · MCP tool

curl -X DELETE "https://outcomeos.cloud/api/v1/org/members/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

GET /api/v1/org/invitations

list_invitations — List pending invitations.

Permission: team:read · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/org/invitations" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

POST /api/v1/org/invitations

invite_member — Invite someone by email. Returns a one-time invite link (also emailed when email sending is configured).

Permission: team:manage · not exposed over MCP

Field	Type	Required	Notes
email	string	yes
role	string	yes	admin | editor | viewer

curl -X POST "https://outcomeos.cloud/api/v1/org/invitations" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden validation conflict

DELETE /api/v1/org/invitations/:iddestructive

revoke_invitation — Revoke a pending invitation.

Permission: team:manage · MCP tool

curl -X DELETE "https://outcomeos.cloud/api/v1/org/invitations/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

GET /api/v1/api-keys

list_api_keys — List API keys (prefix only; keys are stored hashed and cannot be shown again).

Permission: apikeys:manage · not exposed over MCP

curl -X GET "https://outcomeos.cloud/api/v1/api-keys" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

POST /api/v1/api-keys

create_api_key — Create an API key bound to this organization. The full key is returned once.

Permission: apikeys:manage · not exposed over MCP

Field	Type	Required	Notes
name	string	yes

curl -X POST "https://outcomeos.cloud/api/v1/api-keys" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden validation

DELETE /api/v1/api-keys/:iddestructive

revoke_api_key — Revoke an API key immediately.

Permission: apikeys:manage · not exposed over MCP

curl -X DELETE "https://outcomeos.cloud/api/v1/api-keys/<id>" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden not_found

GET /api/v1/templates

list_templates — List outcome and workflow templates.

Permission: outcomes:read · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/templates" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

GET /api/v1/analytics/overview

get_overview — Dashboard overview: active outcomes, verified results, success rate, running and failed executions, recent activity. scope=real (default) or scope=demo; demo and real data are never combined.

Permission: outcomes:read · MCP tool

Field	Type	Required	Notes
days	integer	no	default 30
scope	string	no	real | demo default "real"

curl -X GET "https://outcomeos.cloud/api/v1/analytics/overview" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

GET /api/v1/analytics

get_analytics — Outcome and workflow analytics computed from recorded executions and verified outcome events. scope=real (default) or scope=demo; demo and real data are never combined.

Permission: outcomes:read · MCP tool

Field	Type	Required	Notes
days	integer	no	default 30
scope	string	no	real | demo default "real"

curl -X GET "https://outcomeos.cloud/api/v1/analytics" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

GET /api/v1/assistant/proposals

list_assistant_proposals — List recent assistant proposals.

Permission: assistant:use · MCP tool

curl -X GET "https://outcomeos.cloud/api/v1/assistant/proposals" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

POST /api/v1/assistant/proposals

propose_automation — Turn a plain-language goal into a proposed outcome and draft workflow. Nothing is created until the proposal is approved.

Permission: assistant:use · MCP tool

Field	Type	Required	Notes
prompt	string	yes

curl -X POST "https://outcomeos.cloud/api/v1/assistant/proposals" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Every qualified lead should get a WhatsApp within 5 minutes and a reply within 24 hours"}'

Errors: unauthorized forbidden validation

POST /api/v1/assistant/proposals/:id/approve

approve_assistant_proposal — Approve a proposal: creates the outcome and a draft (unpublished) workflow linked to it.

Permission: workflows:write · MCP tool

curl -X POST "https://outcomeos.cloud/api/v1/assistant/proposals/<id>/approve" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found conflict

POST /api/v1/assistant/proposals/:id/reject

reject_assistant_proposal — Reject a proposal. Nothing is created.

Permission: assistant:use · MCP tool

curl -X POST "https://outcomeos.cloud/api/v1/assistant/proposals/<id>/reject" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_found conflict

GET /api/v1/billing

get_billing — Current plan, limits, usage this month and available plans.

Permission: billing:read · not exposed over MCP

curl -X GET "https://outcomeos.cloud/api/v1/billing" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden

POST /api/v1/billing/checkout

start_checkout — Create a Stripe Checkout session for a paid plan. The plan changes only after Stripe's signed webhook confirms payment.

Permission: billing:manage · not exposed over MCP

Field	Type	Required	Notes
plan	string	yes	growth | business

curl -X POST "https://outcomeos.cloud/api/v1/billing/checkout" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_configured

POST /api/v1/billing/portal

open_billing_portal — Open the Stripe customer portal to manage or cancel the subscription.

Permission: billing:manage · not exposed over MCP

curl -X POST "https://outcomeos.cloud/api/v1/billing/portal" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden not_configured conflict

POST /api/v1/demo/seed

load_demo_data — Load the clearly labelled "never lose a qualified lead" demo: one outcome, one workflow and 100 sample leads. Nothing is sent anywhere.

Permission: demo:manage · not exposed over MCP

curl -X POST "https://outcomeos.cloud/api/v1/demo/seed" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors: unauthorized forbidden conflict not_configured

DELETE /api/v1/demodestructive

clear_demo_data — Remove all demo outcomes, workflows, executions and events from this organization.

Permission: demo:manage · not exposed over MCP

curl -X DELETE "https://outcomeos.cloud/api/v1/demo" \
  -H "Authorization: Bearer $OUTCOMEOS_API_KEY"

Errors: unauthorized forbidden