Skip to main content

​
Overview

The Komos public API lets you launch saved tasks, observe their progress, stream execution logs, and cancel them programmatically. Each run executes asynchronously—enqueue a task, poll for status or subscribe via webhooks, and consume the outputs once the run reaches a terminal state. This is our current public integration surface, while Python and TypeScript SDKs are in active development.

​
Base URLs

  • Production: https://api.komos.ai
Komos does not operate a staging environment; target the production host for all integrations. All endpoints are prefixed with /public/v1. When previewing the docs locally, point the API tester to your tunnel (https://api-komos.ngrok.app) so browser requests reach your development stack.

​
Endpoints

​
Tasks

  • GET /public/v1/tasks — list tasks with embedded schedule, owner, and run statistics.
  • GET /public/v1/tasks/{taskId} — fetch full details for a single task including its definition.

​
Task Runs

  • POST /public/v1/tasks/{taskId}/runs — queue an asynchronous run for a saved task (idempotent with clientRequestId).
  • GET /public/v1/task-runs — list runs across all tasks with status and task filters.
  • GET /public/v1/tasks/{taskId}/runs — list the 50 most recent runs for a specific task.
  • GET /public/v1/task-runs/{runId} — fetch the latest status for a single run.
  • GET /public/v1/task-runs/{runId}/logs — retrieve ordered log entries captured while the run executed.
  • POST /public/v1/task-runs/{runId}/cancel — request cancellation for a pending or running task.

​
Authentication

Authenticate using an organization-scoped API key issued from the Komos dashboard. Send the secret in the Authorization header using the Bearer scheme:
Requests without a valid key return 401 Unauthorized.

​
Idempotency

POST /public/v1/tasks/{taskId}/runs supports idempotent retries via the optional clientRequestId field. Repeat the call with the same value to receive 200 OK and the previously created run instead of launching a duplicate.

​
Run resource

Successful responses return a run object shaped like the example below.
  • status values: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED.
  • triggerType is one of manual, schedule, api, or email.

​
Error handling

Errors follow the standard FastAPI structure:
  • Validation issues return 400 Bad Request with {"detail": "invalid_task_id"}.
  • Missing resources return 404 Not Found, e.g., {"detail": "run_not_found"}.
  • Usage limits return 402 Payment Required with additional details.
  • Transient queue issues respond with 503 Service Unavailable; retry with exponential backoff.

​
Webhooks

Need near-real-time notifications? Configure outbound webhooks from the dashboard to receive run status and log events. Delivery cadence, headers, and payload schemas are detailed in api-reference/webhooks/overview. Refer to the endpoint pages for full schemas and examples.