pipelex/pipelex-api repository overview

⁠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⁠

⁠📑 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.