Pipelex API

The official REST API server for building and executing Pipelex pipelines. Deploy your pipelines as HTTP endpoints and integrate them into any application or workflow.

API Documentation - Pipelex Core - Discord

Released with pipelex, under pipelex's version. This server is the api/ directory of Pipelex/pipelex, and every pipelex release ships it: the pipelex-api package on PyPI pins the pipelex of the same version, and pipelex/pipelex-api:X.Y.Z runs pipelex X.Y.Z. It was released on its own from Pipelex/pipelex-api until v0.33.2, so the image tag that follows 0.33.2 is a pipelex version. The image keeps its name, its port and its /root/.pipelex configuration mount. Please open issues on Pipelex/pipelex.

📑 Table of Contents

• Introduction
• Quick Start with Docker
• Run your first pipeline
• How to scale Pipelex
• API Documentation
• Support
• License

Introduction

The Pipelex API Server is a FastAPI-based REST API that allows you to execute Pipelex pipelines via HTTP requests. Deploy your pipelines as HTTP endpoints and integrate them into any application or workflow.

It is the source-available reference implementation of the MTHDS Protocol — the minimal HTTP contract every MTHDS runner implements (POST /execute, POST /start, POST /validate, GET /models, GET /version). The contracts nest: MTHDS Protocol ⊂ Pipelex API (this server) ⊂ Pipelex hosted API. This server adds the build tooling extensions (/build/*) on top of the protocol; the hosted API at api.pipelex.com/v1 adds durable runs, the method catalog, and account management on top of this server — same shapes throughout. All routes live under the /v1 base path; the committed contract is pipelex-api.openapi.yaml.

🚀 Quick Start with Docker

Official Docker image available at: pipelex/pipelex-api

The published image is generic and configuration-light: Temporal is off, no S3, no remote tracing. It boots with a single required env var (PIPELEX_GATEWAY_API_KEY), and you bring your own Pipelex configuration on top to enable storage, tracing, Temporal, or anything else.

1. Run with Docker

The only required env var is PIPELEX_GATEWAY_API_KEY. Get a free key (with free credits) at https://app.pipelex.com, then run:

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

To require authentication on the API, add -e AUTH_MODE=api_key -e API_KEY=your-secret (or AUTH_MODE=jwt + JWT_SECRET_KEY). See .env.example for the full list of supported variables and the Configuration page for --env-file and docker compose patterns if you'd rather keep config out of your shell history.

If you'd rather 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

The API is now running at http://localhost:8081. To customize behavior (enable Temporal, swap to S3 storage, layer in env-specific overrides, …), see the Configuration page.

🧪 Run your first pipeline

Once /health is green, send an inline pipeline definition and inputs to /v1/execute. The example below summarizes a string with a one-pipe MTHDS bundle — no files, no auth, copy-paste:

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." }
  }'

You'll get back a JSON response with state: "COMPLETED" and the summary under pipe_output.working_memory.root.<main_stuff_name>.content.

Passing files (PDFs, images) as inputs. Use the Document concept and point it at any HTTP(S) URL:

{
  "pipe_code": "your_pipe",
  "mthds_contents": ["...your MTHDS..."],
  "inputs": {
    "cv": { "concept": "Document", "content": { "url": "https://example.com/resume.pdf" } }
  }
}

Document accepts public HTTP/HTTPS URLs, pipelex-storage:// URIs, or base64 data URLs. For images, use the Image concept with the same { "url": "..." } shape.

For inline MTHDS in the request, mthds_contents is a JSON array of raw .mthds (TOML) file contents as strings — typically [open("my_pipe.mthds").read()] from a client. See the Pipe Run page for every supported input shape and the full /execute reference.

📈 How to scale Pipelex

A single Pipelex API container is great for development, prototyping, and low-concurrency workloads — pipelines run in-process and /v1/execute blocks the request thread until they finish.

For production-scale workloads (high concurrency, long-running pipelines, retries, durable execution, horizontal scaling), the recommended path is to run Pipelex on top of Temporal. With Temporal enabled:

• Pipeline runs become durable workflows — survive worker crashes, support retries and timeouts out of the box.
• The API container becomes a thin orchestrator: it submits workflows to a Temporal cluster and returns a pipeline_run_id immediately (this is what POST /v1/start already does).
• Pipeline execution itself runs on a separate pool of Pipelex workers that you scale independently from the HTTP layer.
• Async completion callbacks (callback_urls + X-Completion-Signature, see Pipe Run) let your application be notified when each run finishes, without polling.

Pipelex already integrates with Temporal under the hood, and the Docker image accepts TEMPORAL_API_KEY plus a [temporal] is_enabled = true override in .pipelex/. A complete deployment recipe (Temporal cluster sizing, worker container, autoscaling guidance, and an end-to-end docker-compose) is coming soon. In the meantime, if you need to scale today, get in touch on Discord and we'll help you wire it up.

📖 API Documentation

The full reference for this API server is part of the Pipelex documentation, under API Server:

• Overview — endpoints, authentication, deployment
• Pipe Run — /execute, /start, every input shape
• Pipe Validate — /validate
• Pipe Builder — /build/inputs, /build/output, /build/runner
• Configuration — env vars, mounting your own .pipelex/ config

For broader Pipelex documentation (MTHDS language, concepts, pipe types, the Gateway): https://docs.pipelex.com/

💬 Support

• API Documentation: https://docs.pipelex.com/latest/api-server/
• Pipelex Documentation: https://docs.pipelex.com/
• Discord Community: https://go.pipelex.com/discord
• Main Repository: https://github.com/Pipelex/pipelex

📝 License

This project is licensed under the Elastic License 2.0 (ELv2); see LICENSE for the terms, and the license page for how Pipelex reads them. Runtime dependencies are distributed under their own licenses via PyPI.

"Pipelex" is a trademark of Evotis S.A.S.

© 2025-2026 Evotis S.A.S.