Skip to main content
Pipelex Logo

Pipelex API

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


Elastic License 2.0 Discord Documentation


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

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 tooling extensions (/resolve, /codegen, /pipe-io, /lint, /format) 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 (OPENAI_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 OPENAI_API_KEY: the image enables the openai backend, which serves every default language-model and image-generation tier of its model deck. To run on another provider instead, mount a backends override, as the Configuration page shows. Then run:

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, 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 a method and its inputs to /v1/execute. The method travels in files, a map from each file's path in the method's folder to that file's content. The example below summarizes a string with a method made of a single .mthds file, with no auth, ready to copy and paste:

curl -s http://localhost:8081/v1/execute \
  -H "Content-Type: application/json" \
  -d '{
    "files": {
      "summarize.mthds": "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. The run starts at the method's main_pipe; to start at another pipe of the method, name it in pipe_code.

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

{
  "pipe_code": "your_pipe",
  "files": { "your_method.mthds": "...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.

Sending the method. files holds the whole method, as the MTHDS standard's method tree: each key is a file's path relative to the method's folder, such as summarize.mthds or templates/invoice.docx, and each value is that file's content. A text file, such as a .mthds bundle or a Python module, is sent as its UTF-8 text in a JSON string, and a file that is not text, such as an office template or an image, as {"base64": "..."}. This server also keeps a blob store, which GET /v1/version reports as blob_store: true, so a client can send a file as {"sha256": "...", "size": n} instead: it asks POST /v1/blobs/missing which of its files the server lacks, uploads each of those to the target the answer names, and then sends the method with a hash entry for each file, so a method that has not changed is not uploaded again. The older mthds_contents field, a JSON array of .mthds texts, is still accepted, but it is being retired together with bundle_b64 and resources, and a later release refuses them, so new clients send files. See the Pipe Run page for every supported input shape, the rules of a method sent as a tree and of sending files by hash, 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:

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

💬 Support

📝 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.

Metadata

Release files for pipelex-api 0.95.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pipelex-api 0.95.0
File Size Uploaded Provenance Actions
pipelex_api-0.95.0.tar.gz 171.1 kB With provenance Details for pipelex_api-0.95.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pipelex-api 0.95.0
File Interpreter ABI Platform Actions
pipelex_api-0.95.0-py3-none-any.whl Python 3 none any Details for pipelex_api-0.95.0-py3-none-any.whl

Total release size: 360.8 kB

Release files / pipelex_api-0.95.0.tar.gz

Download URL pipelex_api-0.95.0.tar.gz
Size 171.1 kB
Tags Source
SHA-256 checksum
How to use checksums
dad5b8d9a59f0114acf3d3e3f737a6dd3d1dfe992a2447ba0b2fab6fe92ce6b8
BLAKE2b-256 checksum
How to use checksums
83032ea4577fe8c3b7326468dbc47ca353c290bf792a0821d227e81d8389817b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / pipelex_api-0.95.0-py3-none-any.whl

Download URL pipelex_api-0.95.0-py3-none-any.whl
Size 189.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
35873b6bd6a15501fe2ac40ce400c7c2279d0e57ed96fe72a83361fb6c440b94
BLAKE2b-256 checksum
How to use checksums
f653cea8dd5cf92d54f2f570f805fde066da5a87ccf8078a966ff9f8c1347d8f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for pipelex-api 0.95.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pipelex_api-0.95.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.95.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page