> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinksheep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Programmatic access to Pinksheep agents, runs, and credits.

## 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:

```bash theme={null}
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

```http theme={null}
GET /agents
```

Returns all agents for the authenticated user.

**Response:**

```json theme={null}
{
  "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

```http theme={null}
GET /agents/{agent_uuid}
```

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

### Trigger a run

```http theme={null}
POST /agents/{agent_uuid}/run
```

Triggers a manual run for the specified agent. Returns immediately with a run ID.

**Request body (optional):**

```json theme={null}
{
  "params": {}
}
```

**Response:**

```json theme={null}
{
  "run_id": 42,
  "status": "queued",
  "agent_uuid": "psf-abc123"
}
```

<Info>
  Agents in "propose" mode will execute read steps but pause at write steps pending approval. Check run status to see if approval is needed.
</Info>

### Get run status

```http theme={null}
GET /agents/{agent_uuid}/runs/{run_id}
```

**Response:**

```json theme={null}
{
  "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

```http theme={null}
GET /agents/{agent_uuid}/runs?limit=10
```

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

## Credits

### Get balance

```http theme={null}
GET /credits/balance
```

**Response:**

```json theme={null}
{
  "balance": 142,
  "currency": "credits"
}
```

### List transactions

```http theme={null}
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

```json theme={null}
{
  "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:

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 30 seconds.",
  "retry_after_ms": 30000
}
```