API Overview¶

Base URL¶

http://localhost:3000/api/v1

All API endpoints are prefixed with /api/v1. The health check is the only exception - it lives at /health (no prefix, no version).

Versioning¶

We use URI-based versioning for controllers (e.g., /api/v1/auth, /api/v1/registry). Breaking changes, when they occur, result in a bumped version path.

Authentication¶

Note: The platform is currently in Phase 1 (Foundation), meaning multi-tenant capabilities are not fully completed yet. A single-user authentication scaffold has been set up to facilitate early development.

In the future, the platform will utilize JWT tokens for dashboard access and long-lived API keys for server-to-server interaction (MCP Agents calling MCP DevKit).

Error Response Format¶

Every error from the API follows a standard RFC-compatible shape:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "correlationId": "13850bd4-08fe-4f22-bd5a-b09e13bc6ec2",
  "timestamp": "2026-04-12T11:43:32.488Z",
  "path": "/api/v1/health"
}

Field	Type	Description
`statusCode`	number	HTTP status code
`message`	string or string[]	Human-readable error
`error`	string	HTTP status name
`correlationId`	string (UUID)	Unique request identifier for log tracing
`timestamp`	string (ISO 8601)	When the error occurred
`path`	string	The requested URL path

Correlation ID¶

Every request generates or forwards a x-correlation-id header (UUID v4). This is critical for tracing a complete MCP tool call across the DevKit infrastructure and back to the calling agent.

Health Check¶

GET /health

Returns 200 OK if all dependencies are healthy.

{
  "status": "ok",
  "info": {
    "postgres": {
      "status": "up"
    },
    "redis": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "postgres": {
      "status": "up"
    },
    "redis": {
      "status": "up"
    }
  }
}