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

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.100.1
File Size Uploaded Provenance Actions
pipelex_api-0.100.1.tar.gz 171.1 kB With provenance Details for pipelex_api-0.100.1.tar.gz

Built distribution (wheel)

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

Total release size: 360.8 kB

Release files / pipelex_api-0.100.1.tar.gz

Download URL pipelex_api-0.100.1.tar.gz
Size 171.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a4d149e612fb8ac8deb9e9d1004fbfa191c528cb7ecbdd2db9f8d009c185b9b1
BLAKE2b-256 checksum
How to use checksums
300921eb786702fadbbc1190458c42851008f4fae701902d327787be272ea0f4
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 Nov 13, 2026.

Transparency log

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

Download URL pipelex_api-0.100.1-py3-none-any.whl
Size 189.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2a4f741e687ac4da2032d17710f68727848784a16ee02e6231d3f4cf60914587
BLAKE2b-256 checksum
How to use checksums
a1402b9ce142a4e8b805d7b880afb8490375bda14d9c06a26b0c5ac998c85f60
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 Nov 13, 2026.

Transparency log

Security for pipelex-api 0.100.1

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.100.1.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 Nov 13, 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.100.1 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