Skip to main content

Responses Proxy API reference

The hosted Responses Proxy service is:

https://agent-responses-proxy.svc.cloud.morph.so/

Responses-compatible clients should use:

https://agent-responses-proxy.svc.cloud.morph.so/v1

The live OpenAPI schema is available from the service:

GET /docs
GET /openapi.json

This page summarizes the route families. Use the live schema for exact request and response models.

Health​

GET /healthz
GET /readyz

Expected responses:

{"status": "ok"}
{"status": "ready"}

Responses API proxy​

POST /v1/responses
GET|POST|DELETE|PATCH /v1/responses/{relative_path}
WS /v1/responses

POST /v1/responses forwards the request body to the configured upstream base URL and selected OpenAI resource. Subpaths under /v1/responses/{relative_path} support follow-up operations and response affinity when a resp_* id is available.

Dashboard​

GET /

Returns the live dashboard HTML page.

Live state and telemetry​

GET /admin/state
GET /admin/events
POST /admin/health/check

/admin/state returns Redis-backed resource state, recent decisions, affinity count, queue depth, and current timestamp. /admin/events is a server-sent event stream with the same live state shape. /admin/health/check runs provider health checks immediately.

Current security note: these telemetry endpoints are not protected by PROXY_ADMIN_TOKEN; use network-level controls when exposing them.

Durable history​

GET /admin/sessions?limit=100
GET /admin/requests?limit=100&session_id=...&resource_id=...
GET /admin/decisions?limit=100&session_id=...&resource_id=...&request_id=...

Query limits accept 1 through 500. Requests and decisions can be filtered by session or resource. Request and response bodies are captured in SQL for telemetry, but the current request history API returns metadata, token usage, status, latency, and error fields rather than full bodies.

Provider registry​

Registry routes require bearer auth only when PROXY_ADMIN_TOKEN is set:

Authorization: Bearer <PROXY_ADMIN_TOKEN>

Provider routes:

GET /admin/providers?include_disabled=false
POST /admin/providers
GET /admin/providers/{provider_id}
PATCH /admin/providers/{provider_id}
DELETE /admin/providers/{provider_id}

Create example:

{
  "id": "openai-main",
  "name": "OpenAI Main",
  "provider_type": "openai",
  "base_url": "https://api.openai.com/v1",
  "wire_api": "responses",
  "auth_type": "bearer",
  "credential_ref": "env:OPENAI_API_KEY"
}

Defaults include provider_type: "openai", wire_api: "responses", auth_type: "bearer", auth_header: "authorization", health_path: "models", and enabled: true.

Inline api_key values are write-only, encrypted when PROXY_SECRET_ENCRYPTION_KEY is set, and never returned in plaintext.

Model and agent registry​

GET /admin/models?include_disabled=false
POST /admin/models
GET /admin/models/{alias}
PATCH /admin/models/{alias}
DELETE /admin/models/{alias}

Aliases can contain slashes because the route uses {alias:path}.

Create example:

{
  "alias": "agents/research",
  "display_name": "Research Agent",
  "kind": "compound_agent",
  "provider_id": "openai-main",
  "upstream_id": "gpt-4.1-mini",
  "route": {"type": "responses", "model": "gpt-4.1-mini"},
  "capabilities": {"tools": true, "streaming": true}
}

Allowed kind values are model, agent, and compound_agent.

Current limit: registry entries do not change live routing yet. Runtime routing still uses the configured OpenAI resource environment variables.