API Reference

Overview

The Pinksheep API lets you trigger agent runs, check run status, and manage credits programmatically. All endpoints require authentication via API key.

Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer {your_api_key}" \
  https://app.pinksheep.ai/api/v1/agents

Generate API keys from Settings > API Keys in the dashboard.

Base URL

https://app.pinksheep.ai/api/v1

Agents

List agents

GET /agents

Returns all agents for the authenticated user. Response:

{
  "agents": [
    {
      "agent_uuid": "psf-abc123",
      "name": "Weekly Pipeline Report",
      "status": "active",
      "app_slugs": ["hubspot", "slack"],
      "autonomy": "act",
      "schedule": {
        "cron": "0 8 * * 1",
        "description": "Every Monday at 8am"
      },
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Get agent detail

GET /agents/{agent_uuid}

Returns full agent configuration including execution plan, run history summary, and connection status.

Trigger a run

POST /agents/{agent_uuid}/run

Triggers a manual run for the specified agent. Returns immediately with a run ID. Request body (optional):

{
  "params": {}
}

Response:

{
  "run_id": 42,
  "status": "queued",
  "agent_uuid": "psf-abc123"
}

Agents in “propose” mode will execute read steps but pause at write steps pending approval. Check run status to see if approval is needed.

Get run status

GET /agents/{agent_uuid}/runs/{run_id}

Response:

{
  "run_id": 42,
  "status": "completed",
  "trigger": "manual",
  "steps_completed": 3,
  "credits_used": 2,
  "duration_ms": 4500,
  "step_log": [
    {
      "step_id": "pull_open_deals",
      "status": "completed",
      "duration_ms": 1200
    },
    {
      "step_id": "analyze_health",
      "status": "completed",
      "duration_ms": 2100
    },
    {
      "step_id": "post_summary",
      "status": "completed",
      "duration_ms": 1200
    }
  ],
  "completed_at": "2026-03-14T08:00:04Z"
}

List runs

GET /agents/{agent_uuid}/runs?limit=10

Returns recent runs for the specified agent, ordered by most recent.

Credits

Get balance

GET /credits/balance

Response:

{
  "balance": 142,
  "currency": "credits"
}

List transactions

GET /credits/transactions?limit=20

Returns credit purchase and consumption history.

Webhooks

Pinksheep can send webhook notifications for agent events. Configure webhook URLs from Settings > Webhooks.

Events

Event	Fires when
`run.completed`	An agent run finishes successfully
`run.failed`	An agent run fails
`run.approval_needed`	A run is paused waiting for approval
`credits.low`	Credit balance drops below threshold

Payload format

{
  "event": "run.completed",
  "agent_uuid": "psf-abc123",
  "run_id": 42,
  "timestamp": "2026-03-14T08:00:04Z",
  "data": {
    "status": "completed",
    "credits_used": 2,
    "duration_ms": 4500
  }
}

Rate limits

Endpoint	Limit
Agent runs (per user)	60 / hour
API reads	120 / minute
Credit operations	10 / minute

Rate-limited responses return 429 with a Retry-After header.

Error format

All errors follow a consistent format:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 30 seconds.",
  "retry_after_ms": 30000
}

Getting Started

Building Agents

Reference

Overview

Authentication

Base URL

Agents

List agents

Get agent detail

Trigger a run

Get run status

List runs

Credits

Get balance

List transactions

Webhooks

Events

Payload format

Rate limits

Error format

​Overview

​Authentication

​Base URL

​Agents

​List agents

​Get agent detail

​Trigger a run

​Get run status

​List runs

​Credits

​Get balance

​List transactions

​Webhooks

​Events

​Payload format

​Rate limits

​Error format

Overview

Authentication

Base URL

Agents

List agents

Get agent detail

Trigger a run

Get run status

List runs

Credits

Get balance

List transactions

Webhooks

Events

Payload format

Rate limits

Error format