Skip to main content
Komos offers a lightweight REST API and outbound webhooks so you can launch runs from your own tools and react the moment an automation finishes. Use this page to understand the workflow at a high level, then jump into the detailed references when you are ready to build.

​
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: define an IP allowlist if your infrastructure has fixed egress addresses.

​
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 when you need recent history.
  • 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.

​
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.updated, task-run.succeeded, and task-run.failed 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.