Pipelex API Server

The Pipelex API server runs MTHDS methods over HTTP on infrastructure you host yourself. It is published as the pipelex/pipelex-api Docker image and as the pipelex-api package on PyPI, and its source is the api/ directory of the pipelex repository.

The three-layer contract

This server is the source-available reference implementation of the MTHDS Protocol — the minimal HTTP contract every MTHDS runner implements. The contracts nest:

MTHDS Protocol  ⊂  Pipelex API (this server)  ⊂  Pipelex hosted API
(the standard)     (protocol + extensions)       (+ durable runs, catalog, account)

• MTHDS Protocol — the routes POST /execute, POST /start, POST /validate, GET /models, GET /version, and the blob routes POST /blobs/missing and PUT /blobs/{sha256}, which the protocol makes optional and this server serves, declaring blob_store: true on /version. Tagged x-mthds-protocol: true in the committed OpenAPI artifact, and only those — the flag is how a conformance suite or a third-party runner extracts the portable subset.
• Pipelex API (this server) — the protocol verbatim, plus the Pipelex extensions: resolve and codegen (/resolve, /codegen), pipe I/O (/pipe-io), the model reference check (/models/check), and editor tooling (/lint, /format). /upload and /resolve-storage-url were non-contract convenience routes and have been removed — see Storage Transport for where they went and why.
• Pipelex hosted API (api.pipelex.com/v1) — everything here, same shapes, plus durable runs, the method catalog, and account management.

All routes are served under the /v1 base path (clients compose {base}/v1/{endpoint}).

What the API Offers

The API currently allows you to:

1. Run any Pipelex pipeline with flexible inputs (sync or async)
2. Validate any Pipelex pipeline to ensure correctness
3. Resolve a library closure into its normalized crate, and codegen typed artifacts from it (TypeScript/Zod, Pydantic, Pipelex structures)
4. Describe a method's inputs and output — its pipe I/O contracts, input form and output form, from which a client projects an inputs template
5. Lint and format single .mthds files for editor workflows
6. List available model presets and configurations, and check whether one model reference resolves, as what, to which model

Deployment

Deploy the Pipelex API anywhere that runs Docker (your laptop, ECS, Cloud Run, Kubernetes, …) using our Docker image: pipelex/pipelex-api.

1. Run with Docker

The only required env var is OPENAI_API_KEY. The image enables the openai backend, which serves every default language-model and image-generation tier of its model deck. To call another provider instead, such as Anthropic, Bedrock, Vertex or OpenRouter, mount your own backends override, as the Configuration page shows.

docker run --name pipelex-api -p 8081:8081 \
  -e OPENAI_API_KEY=your-openai-api-key \
  pipelex/pipelex-api:latest

To require authentication on the API itself, add -e AUTH_MODE=api_key -e API_KEY=your-secret (or AUTH_MODE=jwt + JWT_SECRET_KEY). The full set of accepted env vars is documented in Configuration and in the server's .env.example.

If you'd rather keep config out of your shell history, use --env-file .env or a docker-compose.yml instead — see Configuration → Setting env vars in Docker for both patterns.

To build the image yourself instead of pulling, replace pipelex/pipelex-api:latest with a local tag after docker build -f api/Dockerfile -t pipelex-api ., run from the root of a Pipelex/pipelex checkout: the build context is the repository root, so the image installs the pipelex library of the same commit.

2. Verify

curl http://localhost:8081/health

3. Run your first pipeline

Send an inline MTHDS bundle and inputs to /v1/execute:

curl -s http://localhost:8081/v1/execute \
  -H "Content-Type: application/json" \
  -d '{
    "pipe_code": "summarize",
    "mthds_contents": ["domain = \"hello\"\nmain_pipe = \"summarize\"\n\n[pipe.summarize]\ntype = \"PipeLLM\"\ndescription = \"Summarize the input text in one sentence\"\ninputs = { text = \"Text\" }\noutput = \"Text\"\nprompt = \"Summarize in one sentence:\\n@text\"\n"],
    "inputs": { "text": "Pipelex turns plain-language pipeline definitions into reproducible AI workflows that run as HTTP endpoints." }
  }'

The response contains state: "COMPLETED" and the result under pipe_output.working_memory.root.<main_stuff_name>.content. See Pipe Run → for every input shape (text, structured objects, Document, Image, …) and the full /execute and /start reference.

4. Customize the configuration

Need to change the execution mode, point to a different storage backend, or ship your own model deck? See Configuration → for how to provide your own .pipelex/ config files to the Docker image. The base runs every pipeline in-process by default; distributed execution (Temporal, …) is added by a deployment flavor, not configured on the base.

Base URL

Once deployed locally, the API is available at:

http://localhost:8081/v1

To run methods on it from the pipelex CLI, give its origin, without /v1, to --base-url or PIPELEX_BASE_URL: http://localhost:8081. A value with a path is refused before any request is sent. See Running on the Hosted API for what such a server does and does not do for a CLI run.

Authentication

The AUTH_MODE environment variable selects how the API authenticates its callers, with one of the modes below. An unset or empty AUTH_MODE means none. Any other value must spell a mode exactly as written here, lowercase included, or the server refuses to start with an error naming the valid modes: a mistyped mode never serves the API without the authentication it asked for.

No Authentication (Default)

By default (AUTH_MODE=none), the API requires no authentication. This is the default for self-hosted deployments and for running behind an API Gateway that handles auth.

If you sit this API behind a trusted reverse proxy that authenticates users and forwards the caller identity via the X-User-Id header, set TRUST_FORWARDED_IDENTITY_HEADERS=true to honor it. The runner is a generic execution engine — it does not own user metadata (email, OAuth subject, auth method), so a single opaque caller id is the entire trusted surface. The value must be a single path-safe segment (is_safe_user_id). Default is off — without this flag the API ignores X-User-Id entirely and the deployment is treated as single-tenant. With it on, a request arriving without the header is rejected with 401: turning the flag on asserts that a proxy authenticates every caller, so a missing id means that proxy is absent, misconfigured or bypassed. Only enable it when your proxy strips any inbound copy of the header before adding its own; otherwise, any external client can spoof user identity by sending it directly.

API Key Authentication

Set AUTH_MODE=api_key and provide the API_KEY environment variable. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

docker run --name pipelex-api -p 8081:8081 \
  -e AUTH_MODE=api_key \
  -e API_KEY=your-api-key \
  pipelex/pipelex-api:latest

JWT Authentication

Set AUTH_MODE=jwt and provide the JWT_SECRET_KEY environment variable:

docker run --name pipelex-api -p 8081:8081 \
  -e AUTH_MODE=jwt \
  -e JWT_SECRET_KEY=your-jwt-secret-key \
  pipelex/pipelex-api:latest

JWT Requirements:

• Tokens must be signed with the HS256 algorithm
• Tokens must contain a user_id claim that is a single path-safe segment (is_safe_user_id) — it becomes a key segment in storage paths, so provider-issued sub values carrying /, # or : (like "google#abc") are NOT accepted. Deployments using OAuth must mint their own user_id claim mapping each caller to such a value.
• Pass the JWT in the Authorization header: Authorization: Bearer YOUR_JWT_TOKEN

API Endpoints

Every failure is an RFC 7807 application/problem+json problem document — see Error Responses →, and the committed OpenAPI artifact for the statuses each route can produce.

Health & Version

• GET / — Service identity banner (no auth required)
• GET /health — Health check (no auth required)
• GET /v1/version — MTHDS Protocol version handshake (no auth required): {protocol_version, implementation, implementation_version, runtime_version, blob_store}. Replaces the former /pipelex_version and /api_version routes.

Pipe Run

Execute pipelines with flexible input formats, either synchronously or asynchronously.

• POST /v1/execute — Run a pipeline and wait for completion (200 + full result)
• POST /v1/start — Start a pipeline execution without waiting (202 + StartAck)
• POST /v1/blobs/missing — Which of a method's files, by hash, this runner lacks, each with a signed upload target
• PUT /v1/blobs/{sha256} — Upload one blob to its signed target (no bearer token: the signature authorizes it)

Learn more →

Pipe Validate

Validate MTHDS content to ensure pipelines are correctly defined before execution.

• POST /v1/validate — Parse, validate, and dry-run pipelines

Learn more →

Pipe I/O

Read a method's I/O artifacts without a validation. A Pipelex API extension carrying the standard's artifacts.

• POST /v1/pipe-io — The pipe I/O contracts, input form and output form of one pipe, or of every pipe with all_pipes, beside the method's entry pipe and its pending signatures; no dry run. Takes the method as a tree in files or by method_ref, as /v1/resolve and /v1/validate do, and include_files echoes the method's .mthds bundles by tree path

Learn more →

Resolve & Codegen

Resolve a library closure into its normalized crate, and project that crate into typed artifacts. Pipelex API extensions — not MTHDS Protocol routes, though the crate they emit is the standard's Library Crate Format.

• POST /v1/resolve — Resolve a closure into the normalized library crate (fully qualified refs, flattened refinement, materialized natives, fingerprint)
• POST /v1/codegen — Generate typed artifacts from the crate: kind (types) × target (ts-zod, python-pydantic, python-structures), plus the codegen.lock that makes the result reproducible offline

Learn more →

MTHDS Tools

Lint and format single .mthds files without loading or executing a pipeline.

• POST /v1/lint — Return syntax, semantic, or schema diagnostics
• POST /v1/format — Return formatted content, changed status, and blocking syntax diagnostics

Learn more →

Models

List the models this runner can route to, and check one model reference against them.

• GET /v1/models — The protocol model deck this runner routes to (flat models list, plus category-keyed aliases/waterfalls routing extensions); optional single ?type= category filter
• GET /v1/models/check — Whether one model reference (?reference=, optionally in one ?type= category, doc_gen included) resolves on this runner, as what kind of reference and to which model, with suggestions when it does not; answered from pipelex's own parser and the deck lookups a validation runs (Pipelex API extension)

Learn more →

Uploader (removed)

POST /v1/upload and POST /v1/resolve-storage-url have been removed (Storage Transport). The storage provider itself is untouched — only the two HTTP routes are gone.

For most use cases you don't need either: pass any public HTTP(S) URL (or base64 data URL) directly as Document.content.url and skip the upload step entirely.