# Synth HTTP + OpenAI Compatibility Specification

> This spec defines the HTTP contract used by the canonical SDK and the OpenAI-compatible chat surface.

- Skill: `tools-only/synth-http-plus-openai-compatibility-specification` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/synth-http-plus-openai-compatibility-specification`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/synth-http-plus-openai-compatibility-specification/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/synth-http-plus-openai-compatibility-specification

---

# Synth HTTP + OpenAI Compatibility Specification

## 1. Purpose

This spec defines the HTTP contract used by the canonical SDK and the OpenAI-compatible chat surface.

Machine-readable contract: `openapi/synth-api-v1.yaml`.

## 2. Authentication

All authenticated endpoints accept bearer auth:

- `Authorization: Bearer <SYNTH_API_KEY>`

Some clients also send `x-api-key` for compatibility; servers should tolerate both when configured.

## 3. API Areas

### 3.1 Optimization (`/v1/*`)

Canonical resources:

- `/v1/policy-optimization/systems`
- `/v1/offline/jobs`
- `/v1/online/sessions`

These are the default targets for `SynthClient.optimization`.

### 3.2 Inference

OpenAI-compatible chat completions:

- `POST /api/inference/v1/chat/completions`

Contract behavior:

- Request shape mirrors OpenAI Chat Completions.
- Response shape mirrors OpenAI Chat Completions.
- Model IDs are normalized by Synth routing.

Inference jobs:

- `POST /api/inference/jobs`
- `GET /api/inference/jobs/{job_id}`
- `GET /inference/jobs/{job_id}/artifacts/{artifact_id}`

### 3.3 Graphs and verifiers

- `POST /api/graphs/completions`
- `GET /graph-evolve/graphs`

Verifier requests in the SDK are layered on top of graph completions with verifier-shaped inputs.

### 3.4 Containers

Hosted container resources:

- `/api/v1/containers`

### 3.5 Container pools

Pools and rollout control plane:

- `/v1/pools/*`
- `/v1/rollouts/*`

Includes uploads, data sources, assemblies, pools, rollouts, tasks, metrics, and SSE event streams.

### 3.6 SynthTunnel lease API

- `POST /api/v1/synthtunnel/leases`
- `DELETE /api/v1/synthtunnel/leases/{lease_id}`

## 4. Streaming

SSE/event stream endpoints return `text/event-stream` and are consumed as line-delimited `data:` payloads:

- `/v1/offline/jobs/{job_id}/events`
- `/v1/online/sessions/{session_id}/events`
- `/v1/pools/assemblies/{assembly_id}/events`
- `/v1/pools/{pool_id}/rollouts/{rollout_id}/events`

## 5. Compatibility Policy

- Canonical docs must refer to the endpoints in `openapi/synth-api-v1.yaml`.
- OpenAI-compatible schema support is maintained on Synth inference routes.
- Legacy path aliases are outside this spec unless explicitly promoted.