API Reference

Complete reference for the Synth server REST API. The server runs on port 9410 by default. All request and response bodies use JSON (Content-Type: application/json).

Health & System

# Basic health check (no auth required)
curl http://localhost:9410/health

# LLM connectivity status
curl http://localhost:9410/api/health/llm \
  -H "Authorization: Bearer eyJhbG..."

Authentication

Synth uses JWT-based authentication. Access tokens are short-lived; refresh tokens allow obtaining new access tokens without re-authenticating. The JWT signing secret is configured via the SYNTH_JWT_SECRET environment variable.

Login Example

curl -X POST http://localhost:9410/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your-password"
  }'

# Response:
# {
#   "accessToken": "eyJhbG...",
#   "refreshToken": "eyJhbG...",
#   "user": { "id": "...", "username": "admin", "role": "admin" }
# }

API Keys

API keys provide long-lived, scoped authentication for CI/CD pipelines and programmatic access. Each key has a specific set of permissions, limiting what it can do.

Creating a Scoped API Key

# Create a scoped API key
curl -X POST http://localhost:9410/api/auth/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbG..." \
  -d '{
    "name": "ci-pipeline",
    "permissions": ["deployment.create", "deployment.view", "artifact.create"]
  }'

# Use the API key
curl http://localhost:9410/api/operations \
  -H "Authorization: Bearer synth_key_..."

Artifacts

Operations

Create an Operation

curl -X POST http://localhost:9410/api/operations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbG..." \
  -d '{
    "artifactId": "art_abc123",
    "envoyId": "envoy-prod-01",
    "environmentId": "env_production",
    "partitionId": "part_main",
    "variables": {
      "APP_VERSION": "2.4.1",
      "REPLICAS": "3"
    }
  }'

List Operations

# List all operations
curl http://localhost:9410/api/operations \
  -H "Authorization: Bearer eyJhbG..."

# Filter by status
curl "http://localhost:9410/api/operations?status=running" \
  -H "Authorization: Bearer eyJhbG..."

# Filter by partition
curl "http://localhost:9410/api/operations?partitionId=part_main" \
  -H "Authorization: Bearer eyJhbG..."

Partitions

Partitions are optional logical groupings with scoped variables and constraints. Deployments work with or without partition context.

Environments

Envoys

Envoys are lightweight deployment agents running on target machines. The server manages envoy registration, health monitoring, and token rotation.

Agent (Intelligence)

The agent is Synth's reasoning core. It generates deployment plans and produces pre-flight analyses. These endpoints require a configured LLM connection (SYNTH_LLM_API_KEY).

Settings

Users & Roles

Telemetry

Fleet Deployment

Fleet endpoints coordinate deployments across multiple envoys simultaneously.

Deployment Graphs

Deployment graphs define multi-step, dependency-aware deployment workflows as directed acyclic graphs.

Intake (CI/CD Webhooks)

Intake channels receive webhooks from CI/CD systems to automatically trigger deployments when builds complete.

Each intake channel provides a webhook URL specific to the CI/CD provider. Supported providers: GitHub Actions, GitLab CI, Azure DevOps, Jenkins, and CircleCI.

MCP Server

Synth exposes a Model Context Protocol server, making deployment operations available as tools for any MCP-compatible AI client.

MCP sessions have a configurable TTL (default: 1 hour, set via SYNTH_MCP_SESSION_TTL_MS). Idle sessions are cleaned up automatically.

Permissions Reference

Permissions are assigned to roles, and roles are assigned to users. API keys can be scoped to a subset of the creating user's permissions.

Error Responses

All error responses follow a consistent format:

{
  "error": "Short error code",
  "message": "Human-readable description of what went wrong"
}

Rate Limiting

The server enforces per-IP rate limiting. Defaults: 100 requests per 60-second window. Configure via environment variables:

• SYNTH_RATE_LIMIT_MAX — maximum requests per window (default: 100)
• SYNTH_RATE_LIMIT_WINDOW_MS — window duration in milliseconds (default: 60000)

When rate limited, the server returns 429 Too Many Requests with a Retry-After header.