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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.guayaba.run/documentation/api-guide/images-and-media.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.