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

# API Reference

> Complete reference for all Yappr API endpoints.

## Base URL

```
https://api.goyappr.com
```

## Authentication

All requests require an API key passed as a Bearer token:

```bash theme={null}
Authorization: Bearer ypr_live_...
```

Generate keys in the [Yappr dashboard](https://app.goyappr.com) under **Settings → API Keys**. Each key can be scoped to specific permissions.

## API Key Scopes

| Scope                     | Description                                                                                                                                                           |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agents:create`           | Create agents                                                                                                                                                         |
| `agents:read`             | List and get agents                                                                                                                                                   |
| `agents:update`           | Update or deactivate agents                                                                                                                                           |
| `tools:create`            | Create tools                                                                                                                                                          |
| `tools:read`              | List and get tools                                                                                                                                                    |
| `tools:update`            | Attach, detach, or modify tools                                                                                                                                       |
| `phone_numbers:search`    | Search and list phone numbers                                                                                                                                         |
| `phone_numbers:purchase`  | Purchase phone numbers                                                                                                                                                |
| `phone_numbers:configure` | Assign agents to phone numbers                                                                                                                                        |
| `billing:read`            | View billing status                                                                                                                                                   |
| `billing:manage`          | Setup payment method and top up                                                                                                                                       |
| `calls:create`            | Place outbound calls                                                                                                                                                  |
| `calls:read`              | List and get call history                                                                                                                                             |
| `shared_links:read`       | List and get shared links                                                                                                                                             |
| `shared_links:manage`     | Create and revoke shared links                                                                                                                                        |
| `flows:read`              | List flow versions for an agent                                                                                                                                       |
| `flows:test`              | Run the hermetic flow simulator (`POST /agents/:id/flow/test`). Separate from `agents:update` because flow tests can spend money on eval LLMs and external API calls. |
| `integrations:read`       | List third-party integrations connected to your company                                                                                                               |
| `integrations:manage`     | Disconnect (revoke) existing integrations. The public API does not connect new integrations — that happens via the dashboard OAuth flow.                              |
| `do_not_call:read`        | List and look up Do-Not-Call entries                                                                                                                                  |
| `do_not_call:manage`      | Add, update, and remove Do-Not-Call entries                                                                                                                           |
| `dispositions:read`       | List and get call dispositions                                                                                                                                        |
| `dispositions:manage`     | Create, update, and delete call dispositions                                                                                                                          |
| `leads:read`              | List and get leads                                                                                                                                                    |
| `leads:manage`            | Create, update, and delete leads                                                                                                                                      |
| `lead_tags:read`          | List and get lead tags                                                                                                                                                |
| `lead_tags:manage`        | Create, update, and delete lead tags                                                                                                                                  |

## Rate Limiting

**60 requests per minute** per API key. Every response includes:

| Header                  | Description                       |
| ----------------------- | --------------------------------- |
| `X-RateLimit-Limit`     | Requests allowed per window       |
| `X-RateLimit-Remaining` | Requests remaining in window      |
| `X-RateLimit-Reset`     | Unix timestamp when window resets |

## Error Codes

| HTTP Status | Code                 | Description                               |
| ----------- | -------------------- | ----------------------------------------- |
| 400         | —                    | Invalid request (missing or bad field)    |
| 401         | `MISSING_KEY`        | No API key provided                       |
| 401         | `INVALID_KEY`        | API key not found or revoked              |
| 401         | `EXPIRED_KEY`        | API key has expired                       |
| 401         | `INSUFFICIENT_SCOPE` | API key lacks required scope              |
| 402         | `BILLING_ERROR`      | Insufficient balance or no payment method |
| 404         | —                    | Resource not found                        |
| 429         | `RATE_LIMIT`         | Rate limit exceeded                       |
| 500         | —                    | Internal server error                     |

## Discovery

`GET https://api.goyappr.com` (no path, no auth) returns a list of all available endpoints.