HTTP API
HTTP API
The foundational interface to Octopus. Every integration action — whether invoked from the CLI, an MCP tool call,
or a direct application request — ultimately hits this HTTP layer. The CLI wraps it. MCP wraps it.
Everything is a POST /v1/{service}/{method}.
Route Structure
What & Why
The HTTP API is the single canonical interface to every Octopus capability. Rather than exposing a hand-crafted REST API, all routes for integration actions are generated at startup from @service_method decorators — the same decorators that produce CLI commands and MCP tool descriptions.
This means:
- One source of truth. Add a decorator, get an HTTP route, a CLI command, and an MCP tool simultaneously.
- Self-describing.
GET /v1/metareturns the full schema of every registered service and method. Clients can introspect the API without reading documentation. - Uniform request shape. Every action is
POST /v1/{service}/{method}with the method's parameters as top-level JSON keys. No different conventions per service. - Base URL:
http://localhost:3007in development, configurable viaCONSTELLATION_API_URLenv var.
Authentication Methods
Every request goes through APIKeyAuthMiddleware, which resolves one of three credential paths into a RequestContext passed to all downstream handlers:
Header forms accepted:
| Credential type | Header(s) |
|---|---|
| JWT (OAuth token) | Authorization: Bearer <token> |
| API Key | Authorization: ApiKey <key> or X-API-Key: <key> |
| Token passthrough | Access-Token: <raw_token> |
Output Format Negotiation
All /v1/{service}/{method} endpoints support three output formats. Format is selected by the Accept request header or the ?format= query parameter (query param takes precedence):
Use for: Applications, integrations, any downstream processing.
Use for: CLI display, shell scripts, human-readable output.
Use for: LLM tool calls, MCP execution, agentic pipelines.
/v1/meta — Schema Endpoint
GET /v1/meta returns a complete machine-readable description of every service registered at startup. No parameters required. Auth required (any valid credential).
Example response shape:
{
"services": {
"github": {
"description": "GitHub integration service",
"methods": {
"get_repository": {
"description": "Fetch repository details",
"parameters": {
"owner": {"type": "string", "required": true},
"repo": {"type": "string", "required": true}
},
"returns": "object"
}
}
}
}
}
Use /v1/meta to:
- Enumerate all available services and their methods at runtime
- Generate client SDKs or CLI completions automatically
- Verify that a newly-deployed service registered correctly
- Drive the MCP tool-description generation pipeline
Core Endpoints
| Method | Path | Auth required | Description |
|---|---|---|---|
GET | /health | No | Liveness check. Returns {"status": "ok"}. Used by ALB health checks. |
GET | /v1/meta | Yes | Full schema of all registered services and methods. Self-describing API discovery. |
GET | /v1/integrations | Yes | List of connected integrations for the authenticated tenant. |
POST | /v1/{service}/{method} | Yes | Execute any registered service method. Parameters as top-level JSON keys. |
POST | /v1/documents/upload | Yes | Ingest a document: upload, chunk, embed, and index for retrieval. |
POST | /v1/graphrag/query | Yes | Hybrid retrieval query combining vector search and knowledge graph traversal. |
GET | /mcp/{domain}/tools | Yes | List available MCP tools for the given domain. |
POST | /mcp/{domain}/execute | Yes | Execute a single MCP tool with the provided arguments. |
POST | /v1/oauth/{service}/callback | No | OAuth 2.0 callback handler. Exchanges code for tokens and stores credentials. |
Request Headers
| Header | Required | Description |
|---|---|---|
Authorization: Bearer <token> | One of three auth headers | JWT from a connected identity provider (Google, Microsoft, etc.). |
Authorization: ApiKey <key> | One of three auth headers | Octopus-issued API key. Alternative: X-API-Key: <key>. |
Access-Token: <raw_token> | One of three auth headers | Raw token forwarded directly to the service adapter without validation. |
X-API-Key: <key> | No (alternative form) | API key as a standalone header — same effect as Authorization: ApiKey. |
Content-Type: application/json | Yes (POST requests) | All POST bodies must be JSON. |
Accept | No | Controls output format: application/json (default), text/plain, or text/agent. |
X-Tenant-ID | No | Explicitly set tenant context. Usually inferred from the credential. |
Response Envelope
All successful responses from /v1/{service}/{method} are wrapped in a standard envelope:
{
"status": "success",
"data": { },
"meta": {
"service": "github",
"method": "get_repository",
"cached": false,
"duration_ms": 45
}
}
| Field | Type | Description |
|---|---|---|
status | "success" | "error" | Top-level outcome. |
data | object | The method's return value. Shape is method-specific; see /v1/meta for schemas. |
meta.service | string | The service name that handled the request. |
meta.method | string | The method name that was invoked. |
meta.cached | boolean | true if the response was served from the Redis L2 cache. |
meta.duration_ms | number | Wall-clock time in milliseconds from request receipt to response send. |
Error envelope:
{
"status": "error",
"error": {
"code": "ADAPTER_ERROR",
"message": "Repository not found",
"service": "github",
"method": "get_repository"
}
}
Rate Limiting
Rate limits are enforced per tenant by RateLimitMiddleware. Limits and windows are configurable via environment variables. Every response includes the following headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the current window. |
X-RateLimit-Remaining | Requests remaining in the current window. |
X-RateLimit-Reset | Unix timestamp when the current window resets. |
When the limit is exceeded, the server returns HTTP 429 Too Many Requests with a standard error envelope.