API Overview
Authenticate and interact with the GudDesk REST API.
The GudDesk REST API lets you programmatically manage conversations, customers, articles, and agents. Use it to build integrations, automate workflows, or sync data with your other tools.
Base URL
https://your-guddesk-domain.com/api/v1
For the hosted cloud:
https://api.guddesk.com/v1
Authentication
All API requests require an API key. Generate one in Dashboard > Settings > API Keys.
Include the key in the Authorization header:
curl https://api.guddesk.com/v1/conversations \
-H "Authorization: Bearer gd_live_abc123..."API Key Types
| Type | Prefix | Permissions | Visibility |
|---|---|---|---|
| Public | gd_pub_ | Widget only — start conversations, send messages | Safe to expose in client-side code |
| Live | gd_live_ | Full access to production data | Server-side only — never expose |
| Test | gd_test_ | Sandboxed access for development | Server-side only — never expose |
Never use gd_live_ or gd_test_ keys in client-side code, browser scripts, or your chat widget. Use gd_pub_ keys for the widget — they only allow visitors to start conversations, which is the same thing they can already do by visiting your site.
Rate Limits
| Plan | Rate Limit |
|---|---|
| Free | 60 requests/minute |
| Pro | 600 requests/minute |
Rate limit headers are included in every response:
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1686825600
Response Format
All responses return JSON:
{
"data": { ... },
"meta": {
"page": 1,
"perPage": 25,
"total": 142
}
}Error Responses
{
"error": {
"code": "not_found",
"message": "Conversation not found",
"status": 404
}
}Core Endpoints
Conversations
| Method | Path | Description |
|---|---|---|
GET | /conversations | List conversations |
GET | /conversations/:id | Get a conversation |
POST | /conversations | Create a conversation |
POST | /conversations/:id/messages | Send a message |
PATCH | /conversations/:id | Update status, assignee, tags |
Customers
| Method | Path | Description |
|---|---|---|
GET | /customers | List customers |
GET | /customers/:id | Get a customer |
POST | /customers | Create or update a customer |
Knowledge Base
| Method | Path | Description |
|---|---|---|
GET | /articles | List articles |
GET | /articles/:id | Get an article |
POST | /articles | Create an article |
PATCH | /articles/:id | Update an article |
DELETE | /articles/:id | Delete an article |
Agents
| Method | Path | Description |
|---|---|---|
GET | /agents | List agents |
POST | /agents | Deploy a custom agent |
PATCH | /agents/:id | Update agent configuration |
DELETE | /agents/:id | Remove an agent |
Pagination
List endpoints support cursor-based pagination:
GET /api/v1/conversations?limit=25&cursor=conv_abc123| Parameter | Description |
|---|---|
limit | Items per page (default: 25, max: 100) |
cursor | Cursor from previous response's meta.nextCursor |
Next Steps
- Webhooks — Receive real-time events
- Custom Agents — Build automated workflows with the API