> For the complete documentation index, see [llms.txt](https://docs.guayaba.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guayaba.run/documentation/api-guide/images-and-media.md).

# Agents

## List Agents

Returns all agents owned by the API key's user.

```
GET /agents
```

**Auth**: Any key (master or agent).

**Query parameters**:

| Parameter  | Type    | Default | Description      |
| ---------- | ------- | ------- | ---------------- |
| `per_page` | integer | 100     | Results per page |
| `page`     | integer | 1       | Page number      |

```
curl https://api.guayaba.run/api/v1/agents \
  -H "Authorization: Bearer g_master_YOUR_KEY"
```

**Response** (`200`):

```
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Agent",
      "status": "running",
      "channels": ["telegram"],
      "model_provider": "openrouter",
      "settings": { "model": "openai/gpt-4.1" },
      "created_at": "2026-03-15T10:30:00Z"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 100,
  "total": 1
}
```

***

### Show Agent

Returns full details for a specific agent.

```
GET /agents/{id}
```

**Auth**: Master key (any agent) or agent key with `agent:read` scope (own agent only).

```
curl https://api.guayaba.run/api/v1/agents/550e8400-... \
  -H "Authorization: Bearer g_agent_YOUR_KEY"
```

***

### Create Agent

Creates a new AI agent.

```
POST /agents
```

**Auth**: Master key only. **Cost**: 10 credits.

```
curl -X POST https://api.guayaba.run/api/v1/agents \
  -H "Authorization: Bearer g_master_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "llm_provider_name": "openrouter",
    "llm_provider_model": "openai/gpt-4.1",
    "bio": ["You are a helpful support agent."],
    "framework_id": "FRAMEWORK_UUID"
  }'
```

**Response** (`201`):

```
{
  "success": true,
  "message": "Agent created successfully",
  "data": { "id": "...", "name": "Support Bot", "status": "created" }
}
```

***

### Update Agent

Updates an existing agent. Uses PATCH semantics — only provided fields are changed.

```
PUT /agents/{id}
```

**Auth**: Master key only. **Cost**: 10 credits.

**Secrets use PATCH semantics**: send `null` or `""` to delete a secret; omit the key entirely to keep it.

```
curl -X PUT https://api.guayaba.run/api/v1/agents/550e8400-... \
  -H "Authorization: Bearer g_master_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Bot",
    "settings": { "model": "anthropic/claude-sonnet-4.6" }
  }'
```

***

### Delete Agent

Deletes an agent. Stops it first if running. Cascades to API keys and sessions.

```
DELETE /agents/{id}
```

**Auth**: Master key only. **Cost**: Free.

```
curl -X DELETE https://api.guayaba.run/api/v1/agents/550e8400-... \
  -H "Authorization: Bearer g_master_YOUR_KEY"
```

***

### Runtime Control

All runtime endpoints require `agent:manage` scope (master keys always pass).

#### Get Status

```
GET /agents/{id}/status
```

Returns current status, uptime, and timestamps. **Free.**

```
curl https://api.guayaba.run/api/v1/agents/550e8400-.../status \
  -H "Authorization: Bearer g_agent_YOUR_KEY"
```

**Response** (`200`):

```
{
  "status": "running",
  "last_boot_execution": "2026-04-09T08:00:00Z",
  "last_stop_execution": null,
  "uptime_total_seconds": 86400,
  "current_uptime": 3600,
  "server_timestamp": 1744185600000
}
```

#### Health Check

```
GET /agents/{id}/health
```

Returns detailed health for a running agent. **Free.**

#### Start Agent

```
POST /agents/{id}/start
```

Boots the agent or resumes from paused. **Cost**: 5 credits.

#### Stop Agent

```
POST /agents/{id}/stop
```

Stops the agent and accumulates uptime. **Free.**

#### Pause Agent

```
POST /agents/{id}/pause
```

Pauses without stopping the container. **Free.**

#### Reload Config

```
POST /agents/{id}/reload
```

Hot-reloads configuration without restarting. Agent must be running. **Cost**: 1 credit.

***

### Agent Status Values

| Status    | Description                              |
| --------- | ---------------------------------------- |
| `created` | Agent created but never started          |
| `active`  | Provisioning / booting                   |
| `running` | Running and accepting requests           |
| `paused`  | Paused (container alive, not processing) |
| `stopped` | Stopped (no container)                   |
| `failed`  | Failed to start or crashed               |

***

### Sessions

Manage conversation sessions. All session endpoints require `agent:manage` scope.

#### List Sessions

```
GET /agents/{id}/sessions
```

#### Get Session History

```
POST /agents/{id}/sessions/history
```

```
{ "sessionKey": "api:550e8400-...", "limit": 100 }
```

#### Rename Session

```
POST /agents/{id}/sessions/rename
```

```
{ "key": "api:550e8400-...", "label": "Support Conversation #1" }
```

#### Archive Session

```
POST /agents/{id}/sessions/archive
```

```
{ "key": "api:550e8400-..." }
```

#### Delete Session

```
POST /agents/{id}/sessions/delete
```

```
{ "key": "api:550e8400-..." }
```

***

### Archives

#### List Archives

```
GET /agents/{id}/archives
```

#### Restore Archive

```
POST /agents/{id}/archives/restore
```

```
{ "filename": "archive-file.json", "label": "Restored Session" }
```

#### Delete Archive

```
POST /agents/{id}/archives/delete
```

```
{ "filename": "archive-file.json" }
```

***

### Channels (Telegram)

Manage Telegram pairing. All endpoints require `channels` scope.

#### List Pairing Requests

```
GET /agents/{id}/channels/telegram/pairing
```

#### List Approved Pairings

```
GET /agents/{id}/channels/telegram/pairing/approved
```

#### Approve Pairing

```
POST /agents/{id}/channels/telegram/pairing/approve
```

```
{ "code": "PAIRING_CODE" }
```

#### Revoke Pairing

```
POST /agents/{id}/channels/telegram/pairing/revoke
```

```
{ "userId": "TELEGRAM_USER_ID" }
```

#### Reject Pairing

```
POST /agents/{id}/channels/telegram/pairing/reject
```

```
{ "code": "PAIRING_CODE" }
```

***

### Files

Upload files to an agent's knowledge base. Requires `files` scope. The agent must be running.

```
POST /agents/{id}/files
```

```
{
  "filename": "faq.txt",
  "content": "Base64 or plain text content...",
  "mimeType": "text/plain"
}
```

***

### Catalogs

Read-only reference data. Any API key type. Responses are cached for 10 minutes.

| Endpoint                                | Description                |
| --------------------------------------- | -------------------------- |
| `GET /catalogs/frameworks`              | Available agent frameworks |
| `GET /catalogs/frameworks/{id}/clients` | Clients for a framework    |
| `GET /catalogs/regions`                 | Deployment regions         |
| `GET /catalogs/hardware`                | Hardware configurations    |
| `GET /catalogs/models`                  | Available AI models        |
