​
Base URL

https://your-gateway-hostname
Replace with your deployed gateway’s hostname. For local testing, use http://localhost:8180.

​
Authentication

ManyLayers supports three authentication methods: 
Authorization: Bearer ml-your-api-key
API keys are created in gateway.yaml or via POST /admin/keys. Each key is scoped to a team and inherits its model allow-list and rate limits.

​
Request conventions

  • All request bodies are JSON (Content-Type: application/json) unless otherwise noted (e.g. multipart/form-data for file uploads).
  • All /v1/* endpoints accept the same request format as the OpenAI API — no changes needed for existing OpenAI SDK code. See OpenAI Compatibility for the parameter-by-parameter and provider-by-provider matrix.
  • Requests are validated against the OpenAI schema before any provider is contacted, so a malformed request comes back naming the field rather than as a translated provider error.
  • The X-ManyLayers-Config header selects a named routing config for the request.
  • The X-Session-Id header enables sticky sessions to a specific upstream.
  • The X-Request-Id header is returned on every response (auto-generated if not provided by you).

​
Error format

All errors follow the OpenAI error format: 
{
  "error": {
    "message": "Human-readable description",
    "type": "invalid_request_error",
    "param": "temperature",
    "code": "specific_error_code"
  }
}
param is present whenever a specific request field is at fault; the OpenAI SDKs surface it as error.param. Provider errors are translated rather than relayed: an upstream’s status and body are logged server-side and answered in the gateway’s own vocabulary, so behaviour does not depend on which provider happened to serve a model. See the error map.

​
HTTP status codes

StatusMeaning
400Bad request (validation error or firewall block)
401Invalid or missing API key
402Budget or quota exhausted
403Insufficient permissions
404Resource not found
429Rate limit exceeded
500Internal server error
502Upstream provider error
504Upstream timeout or cold-start timeout

​
Endpoint groups

GroupPrefixAuthDescription
Gateway/v1/*API key or OIDCOpenAI-compatible inference endpoints
Workspace/w/*Session cookie or PATChat, knowledge bases, agents, workflows, evals
Admin/admin/*API key (admin role)Team, key, config, and deployment management
Auth/auth/*VariesLogin, signup, SSO, invite flows
SCIM/scim/v2/*SCIM Bearer tokenAutomated user provisioning
Org/org/*Session (org_admin)Org-level billing and SCIM management
Hooks/hooks/*HMAC signatureInbound workflow webhook triggers