Skip to main content

​
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

EventFires when
run.completedAn agent run finishes successfully
run.failedAn agent run fails
run.approval_neededA run is paused waiting for approval
credits.lowCredit 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

EndpointLimit
Agent runs (per user)60 / hour
API reads120 / minute
Credit operations10 / 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
}