Zuplo API Gateway Guide

Build and manage programmable API gateways with Zuplo. This skill teaches you how to find current documentation and correctly configure Zuplo projects.

Critical rule: Read docs before configuring

Before configuring ANY Zuplo feature (policies, handlers, routes, CORS, rate limiting, auth, etc.), you MUST read the relevant documentation first. Do not rely on training data for Zuplo-specific configuration. The docs are the source of truth for correct configuration format, required fields, and available options.

If you skip this step and produce incorrect configuration, it will break the user’s project.

How to look up Zuplo documentation

Use the following sources in priority order:

1. Local docs (preferred): The zuplo npm package bundles full documentation. Look for docs at node_modules/zuplo/docs/ (check both the project root and parent directories for monorepos or hoisted installs). These are version-matched and always available offline.

2. MCP server tools: If the Zuplo MCP server is connected, use search-zuplo-docs and ask-question-about-zuplo (may be prefixed, e.g. mcp__*Zuplo*__search-zuplo-docs).

3. Fetch docs via URL: Fetch https://zuplo.com/docs/llms.txt for a page index, then fetch individual pages. Policy catalog: https://cdn.zuplo.com/portal/policies.v5.json.

Local docs quick reference

Core concepts (summary)

Zuplo is a programmable API gateway built on web standards. Key principles:

• OpenAPI-as-config — routes.oas.json is both the API spec and the routing config
• Web Standards First — Uses Request, Response, Headers, fetch(), Web Crypto, Streams (no Node.js APIs)
• Policy Pipeline — Composable middleware that snaps into a request/response pipeline
• Edge-Native — Global edge deployment by default

Project structure

zuplo.jsonc                    # Project config (version, compatibilityDate)
/config/
  routes.oas.json              # OpenAPI 3.1 spec = routing configuration
/modules/
  *.ts                         # Custom handlers, policies, shared utilities
  zuplo.runtime.ts             # Global runtime extensions and hooks

Request pipeline

Request → Pre-Routing Hooks → Route Matching → Request Hooks
  → Inbound Policies (auth, rate limiting — can short-circuit)
  → Handler (core logic)
  → Outbound Policies (response transformation)
  → Response Hooks → Response sent
  → waitUntil tasks (background work)

Key imports

import {
  ZuploRequest, ZuploContext, RuntimeExtensions, HttpProblems,
  ZoneCache, environment,
} from "@zuplo/runtime";

For full details on handlers, runtime objects, caching, authentication, and deployment models, read the docs in node_modules/zuplo/docs/concepts/.

When you see errors

1. Read the relevant doc page for the feature causing the error (check node_modules/zuplo/docs/ first)
2. Verify configuration matches the documented format exactly
3. Check that all required fields are present
4. For build failures, check deployment logs for specific error messages

Development workflow

1. Read the docs for the feature you’re configuring — check node_modules/zuplo/docs/ or use MCP tools
2. Check available policies — read node_modules/zuplo/docs/policies/_index.md for the full list, then the specific policy’s doc.md for configuration
3. Write configuration based on current docs (never from memory)
4. Verify the build succeeded after saving changes