Getting started

This guide takes you from zero to a completed agent run: you will authenticate, create a run, and poll it until it finishes.

Prerequisites

• A Sirius API key (sirius_sk_...). Ask your workspace admin or the Sirius team if you don't have one yet — self-serve key management is coming.
• curl and jq, or any HTTP client.

Store the key in your shell so the examples below work as-is:

export SIRIUS_API_KEY="sirius_sk_..."

1. Check the service

GET /v1/health requires no authentication and confirms you can reach the API:

curl https://api.thesirius.ai/v1/health

{ "status": "ok", "version": "0.1.0" }

2. Create an agent run

A run is one task executed by the Hermes Managed Agent. Create one with POST /v1/agent/runs:

curl https://api.thesirius.ai/v1/agent/runs \
  -H "Authorization: Bearer $SIRIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Summarize the last 7 days of sign-ups and flag anomalies."
  }'

The API responds immediately — runs execute asynchronously:

{
  "id": "run_01j9x6q8ftq",
  "status": "queued",
  "input": "Summarize the last 7 days of sign-ups and flag anomalies.",
  "created_at": "2026-07-06T12:00:00Z"
}

Keep the id; it is how you refer to the run from now on.

3. Poll until it finishes

Fetch the run with GET /v1/agent/runs/{run_id} until status reaches a terminal state (succeeded, failed or canceled):

curl https://api.thesirius.ai/v1/agent/runs/run_01j9x6q8ftq \
  -H "Authorization: Bearer $SIRIUS_API_KEY" | jq .status

When the run succeeds, output contains the result:

{
  "id": "run_01j9x6q8ftq",
  "status": "succeeded",
  "output": "Sign-ups grew 12% week-over-week. One anomaly: ...",
  "completed_at": "2026-07-06T12:01:24Z"
}

Next steps

• Browse the full API reference — request/response schemas, error codes and an interactive playground for every endpoint.
• Read Authentication before deploying anything.
• Watch the changelog for new capabilities.