API Reference

All REST endpoints are served through the Gateway. Base URL: https://gateway.apexmcp.ai

Interactive API explorer: https://gateway.apexmcp.ai/swagger

Authentication

All endpoints (except /oauth/token) require an X-API-Key header or Authorization: Bearer <token> header.

Endpoints

`POST /oauth/token`

Exchange client credentials for a Bearer JWT.

Request body (application/x-www-form-urlencoded):

Parameter	Required	Description
`grant_type`	Yes	Must be `client_credentials`
`client_id`	Yes	OAuth client ID
`client_secret`	Yes	OAuth client secret
`scope`	No	Space-separated scopes (default: `mcp:call`)

Response:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mcp:call"
}

`GET /api/connectors`

List all connectors in the authenticated organisation.

Response:

{
  "connectors": [
    {
      "id": "conn_01j9x8k2m3n4p5q6r7s8t9u0v1",
      "name": "production-db",
      "type": "postgresql",
      "status": "healthy",
      "tool_count": 12,
      "created_at": "2024-10-01T09:00:00Z"
    }
  ]
}

`POST /api/connectors`

Create a new connector.

Request body (application/json):

{
  "name": "production-db",
  "type": "postgresql",
  "config": {
    "host": "db.example.com",
    "port": 5432,
    "database": "mydb",
    "username": "apexmcp_ro",
    "password": "••••••••",
    "ssl": true
  }
}

Response: 201 Created with connector object.

`GET /api/agents`

List registered agents for the organisation.

Response:

{
  "agents": [
    {
      "id": "agent_01abc",
      "name": "reporting-agent",
      "created_at": "2024-10-15T12:00:00Z",
      "last_seen_at": "2024-11-15T14:32:01Z"
    }
  ]
}

`POST /api/agents`

Request body:

{
  "name": "reporting-agent",
  "description": "Automated reporting pipeline"
}

Response: 201 Created with agent object.

`GET /api/audit`

Retrieve audit log entries for the organisation.

Query parameters:

Parameter	Type	Description
`from`	ISO 8601	Start of time range
`to`	ISO 8601	End of time range
`connector_id`	string	Filter by connector
`agent_id`	string	Filter by agent
`limit`	integer	Max entries (default 100, max 1000)
`cursor`	string	Pagination cursor from previous response

Response:

{
  "entries": [
    {
      "id": "aud_01xyz",
      "timestamp": "2024-11-15T14:32:01.482Z",
      "tool_name": "query_postgres_orders",
      "connector_id": "conn_01j9x8k2m3n4p5q6r7s8t9u0v1",
      "agent_id": "agent_01abc",
      "duration_ms": 143,
      "success": true,
      "error_code": null
    }
  ],
  "next_cursor": "aud_01abc"
}

`POST /mcp/:orgSlug`

The main MCP JSON-RPC endpoint. See MCP Protocol for full documentation.

Supported methods:

tools/list — list all available tools
tools/call — execute a tool

Error Responses

All API errors follow a consistent format:

{
  "error": {
    "code": "connector_not_found",
    "message": "No connector found with id conn_xxxx",
    "status": 404
  }
}

HTTP Status	Meaning
`400`	Bad request — validation error
`401`	Unauthenticated
`403`	Forbidden — insufficient permissions
`404`	Resource not found
`409`	Conflict — resource already exists
`422`	Unprocessable — semantic validation failed
`429`	Rate limited
`500`	Internal server error

SDKs Self-Hosting