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.

🚀 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 docs/configuration.md 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 -t pipelex-api ..

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 docs/configuration.md.

🧪 Run your first pipeline

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

curl -s http://localhost:8081/api/v1/pipeline/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 pipeline_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 docs/pipe-run.md 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 /api/v1/pipeline/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 /api/v1/pipeline/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.md) 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 lives next to the code in docs/:

• 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/pages/api/
• 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 MIT license. 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.