# zuplo-guide

Guide for configuring Zuplo API gateway routes, policies, and custom handlers, using current official docs as the source.

Skill by Zuplo. Category: Knowledge.

## Install

Project (for this project only):

```sh
npx skills add zuplo/tools --skill zuplo-guide
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add zuplo/tools --skill zuplo-guide -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 22. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/zuplo/tools/zuplo-guide)

## Source

[Open the source](https://github.com/zuplo/tools/tree/HEAD/skills/zuplo-guide). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: zuplo-guide
description: "Use when building or maintaining a Zuplo API gateway project, including configuring routes and policies, writing custom handlers, understanding the request pipeline, and managing deployments. Covers documentation lookup strategies (llms.txt, individual doc pages), core concepts (OpenAPI-as-config, policy pipeline, web standards runtime), and all built-in policies, so configuration comes from official docs."
license: MIT
metadata:
  author: Zuplo
  version: "1.0.0"
  repository: https://github.com/zuplo/tools
---

# 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

| Topic | Path in `node_modules/zuplo/docs/` |
| ----- | ---------------------------------- |
| Concepts (request lifecycle, project structure) | `concepts/` |
| Policies (index + per-policy config/schema) | `policies/_index.md`, `policies/{policy-id}/doc.md`, `policies/{policy-id}/schema.json` |
| Handlers (URL forward, rewrite, custom, etc.) | `handlers/` |
| Articles (CORS, env vars, auth, deployment) | `articles/` |
| CLI reference | `cli/` |
| Monetization | `articles/monetization/` |
| Developer portal / Zudoku | `dev-portal/` |
| Programmable API reference | `programmable-api/` |
| Guides | `guides/` |

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

```ts
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
````

- Previous: [paragon-actionkit-skill](https://syn4pse.dev/terminal/paragon-actionkit-skill.md)
- Next: [zuplo-cli](https://syn4pse.dev/terminal/zuplo-cli.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
