REST API
Base URL, authentication, errors, and pagination for the Dexby REST API.
Quick reference
- Base URL:
https://api.dexby.ai - Auth:
Authorization: Bearer $DEXBY_API_KEYon every/v1route - Body: JSON with
Content-Type: application/json - Success:
{ "data": ... } - Error:
{ "error": { "code": "...", "message": "..." } }
curl "https://api.dexby.ai/v1/connectors?limit=5" \
-H "Authorization: Bearer $DEXBY_API_KEY"Authentication
Send a project API key as a bearer token.
| Rule | Detail |
|---|---|
| Format | dx_ followed by 64 hex characters. |
| Where to get it | The dashboard, Configure → API keys → Create. It is shown once. |
| Project | A key belongs to one project. The key decides the project, so no /v1 route takes a project id. |
| Revocation | Revoking a key in the dashboard stops it at once. An expired key stops at its expiry. |
| Failure | A missing, unknown, revoked, or expired key answers 401 UNAUTHORIZED. |
| Server only | /v1 sends no CORS headers. Call it from your server, never from a browser, and keep the key out of client bundles. |
Requests
- A body that is not valid JSON is read as
{}, so required fields then fail validation. - Boolean query parameters take
trueorfalse. - Path parameters are written
:idstyle in these docs, for example/v1/sessions/:id/mcp.
Errors
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request body",
"issues": [
{
"code": "invalid_type",
"path": ["userId"],
"message": "Invalid input: expected string, received undefined"
}
]
}
}Branch on code; message can change. issues comes with VALIDATION_ERROR, and choices
(the user's accounts as { id, displayName }) with AMBIGUOUS_CONNECTION.
| Status | Codes |
|---|---|
| 400 | VALIDATION_ERROR, MISSING_CONNECTION, REAUTH_REQUIRED, CONNECTION_NOT_FOUND, EXECUTION_ERROR |
| 401 | UNAUTHORIZED |
| 403 | ACTION_DISABLED, FORBIDDEN_ENDPOINT |
| 404 | NOT_FOUND, TOOL_NOT_FOUND, CONNECTOR_NOT_FOUND, SESSION_NOT_FOUND, CONNECTION_NOT_FOUND |
| 405 | No body. GET or DELETE on an MCP route. |
| 409 | AMBIGUOUS_CONNECTION, CONFLICT, NAME_TAKEN, CONNECTOR_UNAVAILABLE |
| 500 | INTERNAL_ERROR, EXECUTION_ERROR (a failed credential rotation) |
| 502 | UPSTREAM_ERROR |
| 503 | CREDENTIAL_UNAVAILABLE |
What each code means and how to fix it: errors.
Pagination
GET /v1/connectors, GET /v1/tools, and the public GET /api/catalog return one page at a
time. Every other list returns all items at once.
| Query | Default | Rule |
|---|---|---|
limit | 100 | Integer, 1 to 500. |
cursor | none | The previous page's nextCursor, 1 to 300 characters. |
A page answers { "data": [...], "nextCursor": "..." }. nextCursor is null on the last
page. Pass facets=true to add counts per category.
Rate limits
/v1 has no per-key rate limit. Limits at the provider come back as UPSTREAM_ERROR or
EXECUTION_ERROR.
Resources
| Resource | Routes |
|---|---|
| Connectors | GET /v1/connectors, GET /v1/connectors/:id |
| Tools | GET /v1/tools, POST /v1/tools/execute, POST /v1/tools/proxy |
| Sessions | POST /v1/sessions, GET /v1/sessions/:id, /tools, /tools/:name, /mcp |
| Connections | GET, POST /v1/connections, PATCH, DELETE /v1/connections/:id, /default |
| Connect links | POST /v1/connect-links |
| Triggers | GET, POST /v1/triggers, DELETE /v1/triggers/:id |
| MCP | POST https://mcp.dexby.ai/:slug/:userId, POST /v1/mcp/:slug/:userId |
Routes that need no API key (catalog, health, assets, trigger ingress, the hosted Connect page) are in public endpoints.