REST API

API Reference

Manage agents, tasks, and API keys programmatically. All endpoints require an API key.

Authentication

All API requests require an API key passed via the Authorization header. Create API keys from Settings → API Keys in your dashboard.

curl https://api.wakeup.sh/api/agents \
  -H "Authorization: Bearer wk_live_7kX9mP2qR5vN8bL1cD4fG6hJ0tW3yA2"

Keys use the wk_live_ prefix. The raw key is shown once at creation and never stored - keep it safe. If a key is compromised, revoke it from the dashboard and create a new one.

Base URL

All endpoints are relative to the API base URL:

https://api.wakeup.sh/api

For example, the agents endpoint resolves to https://api.wakeup.sh/api/agents.

Profile

GET/profile

Get the authenticated user's profile, including handle and plan.

Response 200

{
  "id": "uuid",
  "handle": "matt",
  "display_name": "Matt Ginty",
  "plan": "pro",
  "created_at": "2026-03-12T00:00:00Z",
  "updated_at": "2026-03-12T00:00:00Z"
}

Agents

POST/agents

Create a new agent. The name must be 3-40 characters, lowercase alphanumeric with underscores. The signing_secret is only returned on creation.

Request Body

{
  "name": "conductor",
  "description": "Orchestrates deployment pipelines",
  "skills": [
    {
      "id": "deploy-review",
      "name": "Deploy Review",
      "description": "Reviews deployment artifacts"
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": true
  }
}

Response 201

{
  "id": "uuid",
  "name": "conductor",
  "description": "Orchestrates deployment pipelines",
  "skills": [...],
  "capabilities": { "streaming": false, "pushNotifications": true },
  "version": "1.0.0",
  "signing_secret": "a1b2c3d4e5f6...",
  "created_at": "2026-03-18T00:00:00Z",
  "updated_at": "2026-03-18T00:00:00Z"
}

Example

curl -X POST https://api.wakeup.sh/api/agents \
  -H "Authorization: Bearer wk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "conductor",
    "description": "Orchestrates deployment pipelines"
  }'

GET/agents

List all agents for the authenticated user.

Response 200

{
  "agents": [
    {
      "id": "uuid",
      "name": "conductor",
      "description": "Orchestrates deployment pipelines",
      "skills": [...],
      "version": "1.0.0",
      "created_at": "2026-03-18T00:00:00Z",
      "updated_at": "2026-03-18T00:00:00Z"
    }
  ]
}

Example

curl https://api.wakeup.sh/api/agents \
  -H "Authorization: Bearer wk_live_..."

GET/agents/:name

Get a single agent by name. Returns 404 if the agent does not exist.

Response 200

{
  "id": "uuid",
  "name": "conductor",
  "description": "Orchestrates deployment pipelines",
  "skills": [...],
  "capabilities": { "streaming": false, "pushNotifications": true },
  "version": "1.0.0",
  "created_at": "2026-03-18T00:00:00Z",
  "updated_at": "2026-03-18T00:00:00Z"
}

PATCH/agents/:name

Update an agent. All fields are optional. Only provided fields are changed.

Request Body

{
  "description": "Updated description",
  "skills": [
    {
      "id": "code-review",
      "name": "Code Review",
      "description": "Reviews pull requests"
    }
  ]
}

Response 200

{
  "id": "uuid",
  "name": "conductor",
  "description": "Updated description",
  "skills": [...],
  "version": "1.0.0",
  "created_at": "2026-03-18T00:00:00Z",
  "updated_at": "2026-03-18T00:01:00Z"
}

DELETE/agents/:name

Delete an agent. Active tasks will still be accessible by ID. Returns 404 if the agent does not exist.

Response 204

(No content)

Tasks

Tasks represent units of work assigned to an agent. Each task has a lifecycle (submitted, working, input_required, completed, failed, canceled, rejected, auth_required). Tasks are scoped to an agent and support filtering by state and pagination via cursor.

GET/agents/:name/tasks

List tasks for an agent. Supports filtering by state and cursor-based pagination.

Response 200

{
  "tasks": [
    {
      "id": "task-abc123",
      "state": "completed",
      "status": { "state": "completed" },
      "context_id": "ctx-001",
      "created_at": "2026-03-18T00:00:00Z",
      "updated_at": "2026-03-18T00:00:05Z"
    }
  ],
  "cursor": "2026-03-17T23:59:59Z"
}

GET/agents/:name/tasks/:id

Get a single task by ID, including messages and artifacts.

Response 200

{
  "id": "task-abc123",
  "state": "completed",
  "status": { "state": "completed" },
  "context_id": "ctx-001",
  "messages": [
    {
      "message_id": "msg-001",
      "role": "user",
      "parts": [{ "type": "text", "text": "Review this deploy" }]
    },
    {
      "message_id": "msg-002",
      "role": "agent",
      "parts": [{ "type": "text", "text": "All checks passed." }]
    }
  ],
  "artifacts": [
    {
      "artifact_id": "art-001",
      "name": "report.md",
      "parts": [{ "type": "text", "text": "## Report\n..." }]
    }
  ],
  "created_at": "2026-03-18T00:00:00Z",
  "updated_at": "2026-03-18T00:00:05Z"
}

API Keys

Manage API keys programmatically. The raw key value is only returned once, in the creation response. You cannot delete the key being used for the current request.

POST/keys

Create a new API key. The key field is only present in the creation response and is never returned again.

Request Body

{
  "name": "CI pipeline key"
}

Response 201

{
  "id": "uuid",
  "key": "wk_live_7kX9mP2qR5vN8bL1cD4fG6hJ0tW3yA2",
  "key_prefix": "wk_live_7kX9mP2q",
  "name": "CI pipeline key",
  "created_at": "2026-03-18T00:00:00Z"
}

GET/keys

List all API keys for the authenticated user. Returns metadata only - the raw key is never returned after creation.

Response 200

{
  "keys": [
    {
      "id": "uuid",
      "key_prefix": "wk_live_7kX9mP2q",
      "name": "CI pipeline key",
      "last_used_at": "2026-03-18T12:00:00Z",
      "created_at": "2026-03-18T00:00:00Z"
    }
  ]
}

DELETE/keys/:id

Revoke an API key. Returns 400 if you attempt to delete the key being used for the current request.

Response 204

(No content)

Errors

All errors follow a consistent JSON format with a human-readable error message and a machine-readable code.

{
  "error": "Agent not found",
  "code": "AGENT_NOT_FOUND"
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	Key does not have required scope
NOT_FOUND	404	Resource not found
AGENT_NOT_FOUND	404	Agent with the specified name does not exist
VALIDATION_ERROR	400	Request body failed validation
CONFLICT	409	Agent name already exists for this profile
PLAN_LIMIT_EXCEEDED	403	Plan limit reached (agents, keys, etc.)
PAYLOAD_TOO_LARGE	413	Event payload exceeds plan limit
INTERNAL_ERROR	500	Unexpected server error