API Reference

The AgentBridge REST API follows predictable conventions. All requests use JSON bodies. All responses return a consistent envelope. This page covers the global rules that apply to every endpoint.

Base URL #

All API endpoints are relative to this base URL. The API is served exclusively over HTTPS — plain HTTP requests receive a 301 Moved Permanently redirect. HSTS is enabled with a max-age of one year and includeSubDomains. All data is hosted in AWS ap-south-1 (Mumbai).

Versioning #

The current API is v1. There is no version prefix in the URL — all endpoints are available directly under the base URL (e.g. /api/mcp/execute, not /v1/api/mcp/execute).

When breaking changes are introduced in the future, they will be published under a versioned path prefix (e.g. /v2/) with a minimum 6-month deprecation notice and migration guide. Non-breaking additions (new fields in responses, new optional parameters, new endpoints) are made to v1 without versioning.

Request Format #

• All request bodies must be valid JSON (UTF-8 encoded)
• Set Content-Type: application/json on every POST, PUT, and PATCH request
• Authenticate with Authorization: Bearer <your-api-key> (see Authentication)
• Query parameters use standard URL encoding
• Request body size limit: 1 MB

curl -X POST https://api.agentbridge.in/api/mcp/execute \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "slack",
    "tool": "send_message",
    "params": {
      "channel": "C012AB3CD",
      "text": "Hello from AgentBridge"
    }
  }'

Response Format #

Success Response #

Successful responses return HTTP 200 or 201 with a JSON envelope:

{
  "status":      "success",
  "data":        { /* endpoint-specific payload */ },
  "latencyMs":   247,
  "executionId": "exec_01HXZ..."
}

Error Response #

Errors return the appropriate HTTP status code with a JSON error envelope:

{
  "statusCode":    422,
  "message":       "Provider returned an error",
  "error":         "Unprocessable Entity",
  "providerError": {
    "code":    "object_not_found",
    "message": "Could not find page with ID: abc123"
  }
}

See the Error Reference for the complete error catalog with provider-specific examples.

All Endpoints #

HTTP Status Codes #

Pagination #

Endpoints that return lists (e.g. GET /logs, GET /api-keys) support offset-based pagination via page and limit query parameters.

The response envelope for paginated endpoints includes total count and current position:

{
  "status": "success",
  "data": {
    "data":  [ /* array of items */ ],
    "total": 84,
    "page":  2,
    "limit": 20
  },
  "latencyMs": 43
}

curl "https://api.agentbridge.in/logs?page=2&limit=50" \
  -H "Authorization: Bearer ab_live_xxxx"

To calculate whether more pages exist, check if page * limit < total. If true, increment page and make another request.

Content Negotiation #

The API always responds with Content-Type: application/json; charset=utf-8. All responses are JSON. Do not set Accept headers that exclude JSON — requests with an Accept header that cannot be satisfied will receive a 406 Not Acceptable response.

Request bodies must also be JSON. Sending Content-Type: application/x-www-form-urlencoded or multipart/form-data will result in a 400 Bad Request error.