API & Webhooks

​

Get ready

1. In the Komos app, go to Settings → API & Webhooks.
2. Create an Organization API key and store it in a secure location (vault, CI secret, or server config).
3. Optional: register a webhook endpoint to receive run lifecycle events.

​

Browse tasks via API

• Call GET /public/v1/tasks to list all tasks in your organization with their schedule, owner, and run statistics.
• Use GET /public/v1/tasks/{taskId} to fetch full details for a single task including its definition and plan summary.
• Full parameter and schema details live in the Tasks API reference.

​

Launch runs from your systems

• Call POST /public/v1/tasks/{taskId}/runs with your API key to start a run on demand. Supply task inputs in the body; omit any fields that should fall back to the defaults you set in the builder.
• Use GET /public/v1/task-runs/{runId} to check the latest status, or GET /public/v1/task-runs to list runs across all tasks.
• Stream detailed logs with GET /public/v1/task-runs/{runId}/logs if you want to mirror the mission control timeline inside your own monitoring tools.
• Full parameter and schema details live in the Task Runs API reference. JSON responses now include object and object_list output shapes when you declare those types in your task outputs.

​

Example: queue a run

curl -X POST "https://api.komos.ai/public/v1/tasks/123/runs" \
  -H "Authorization: Bearer $KOMOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "account_id": "acct_987",
      "month": "2025-10"
    }
  }'

​

Stay in sync with webhooks

• Still on Settings → API & Webhooks, register an HTTPS endpoint and copy the signing secret.
• Komos delivers task-run.started, task-run.completed, task-run.failed, task-run.cancelled, and task-run.log events. Each payload includes the run ID, task metadata, and the latest status so you can take action immediately.
• Validate every request using the HMAC signature in the X-Komos-Signature header before trusting the payload. The Webhooks overview supplies code samples and the retry policy.

​

Put it together

• Kick off a run via API, then use webhooks to notify your team in Slack, update a CRM, or trigger a downstream process when the automation succeeds.
• For high-volume automations, act on success webhooks and only inspect detailed logs when a failure event arrives.
• Keep API keys and webhook secrets separate so rotating one credential does not break the other.

​

Good habits

• Limit API keys to server-side environments you control.
• Test integrations on a staging task before connecting them to production workflows.
• Monitor webhook delivery health in the dashboard and replay any failed events once your endpoint is back online.