Base URL
Authentication
All requests require an API key passed as a Bearer token: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 |
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.