Skip to main content

​
1. Get an API key

Sign up at operator.io and create an API key in Settings > API Keys. Keys start with ck_live_. 
export OPERATOR_API_KEY="ck_live_..."

​
2. Verify your key

curl -s "https://operator.io/api/cli/health" \
  -H "Authorization: Bearer $OPERATOR_API_KEY" | jq

{
  "authenticated": true,
  "userId": "user_...",
  "planSlug": "pro",
  "hasPlan": true,
  "tokenLimit": 15000000
}

​
3. Send your first message

The /api/chat endpoint accepts messages and returns a response from the Operator agent. It can deploy agents, create instances, manage secrets, and schedule automations. 
curl -s "https://operator.io/api/chat" \
  -H "Authorization: Bearer $OPERATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-response-format: json" \
  -d '{
    "messages": [{
      "role": "user",
      "parts": [{ "type": "text", "text": "Create a prebuilt instance called weather-desk." }]
    }]
  }' | jq

{
  "chatId": "chat_abc123",
  "text": "Created instance weather-desk. It is provisioning now and should be active in about 30 seconds."
}

​
4. Continue a conversation

Pass the chatId from the previous response as id to continue the same conversation. The Operator agent retains context across messages. 
curl -s "https://operator.io/api/chat" \
  -H "Authorization: Bearer $OPERATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-response-format: json" \
  -d '{
    "id": "chat_abc123",
    "messages": [{
      "role": "user",
      "parts": [{ "type": "text", "text": "Install a skill that predicts AQI for 50 cities. Score daily against actual readings." }]
    }]
  }' | jq

​
5. List your instances

curl -s "https://operator.io/api/instances" \
  -H "Authorization: Bearer $OPERATOR_API_KEY" | jq '.instances[] | {id, name, status}'

{
  "id": "inst_...",
  "name": "weather-desk",
  "status": "active"
}

​
6. Add secrets

Agents need credentials to access external services. Store them as secrets and grant them to instances. 
# Create a secret
curl -s "https://operator.io/api/secrets" \
  -H "Authorization: Bearer $OPERATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "OPENWEATHER_API_KEY", "value": "owm_..." }' | jq

# Grant it to your instance
curl -s "https://operator.io/api/instances/inst_.../secrets" \
  -H "Authorization: Bearer $OPERATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "secretId": "sec_..." }' | jq

​
7. Schedule work

Create an automation to run the agent on a schedule: 
curl -s "https://operator.io/api/automations" \
  -H "Authorization: Bearer $OPERATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily AQI scoring",
    "prompt": "Score all AQI predictions against yesterday actuals and report results.",
    "cronExpression": "0 9 * * *",
    "timezone": "America/New_York"
  }' | jq

​
Next steps

API Reference

Full interactive reference with every endpoint.

Agents

How agents work: build, test, improve.

Instances

What an instance can do.

Webhooks

Trigger agents from external events.