> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zap.wzrd.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Zap Web App: Routes, Auth Posture, and REST API Reference
> The Zap web app at zap.wzrd.tech hosts the creator runner, agent studio, gallery, docs, and REST API. Learn the route map and auth posture.
The Zap web app, deployed at [zap.wzrd.tech](https://zap.wzrd.tech), is the primary surface for everyone who builds with or runs Zap. **Creators** use it to trigger one-click recipe runs and manage their provider vault. **Agents** (Codex, Claude Code, Cursor, OpenClaw, Hermes, and similar tools) use the skill manifest endpoints and mock run commands as a starting point. **Developers** call the REST API directly to integrate recipe execution into their own pipelines.
## Primary Routes
| Route | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `/` | Public landing page — showcases installed recipes, signals the runtime contract, and links to the agent quickstart. |
| `/gallery` | Installed Zap gallery — browse every recipe packaged in the current deployment. |
| `/docs` | Docs entry point — full reference documentation browsable in-app. |
| `/quickstart` | Agent quickstarts for Codex, Claude Code, Cursor, OpenClaw, Hermes, and similar tools. |
| `/studio` | Eve-powered agent studio — chat-driven recipe authoring and execution. |
| `/zap/[slug]` | One-click creator runner for a specific recipe slug (e.g. `/zap/world-cup-entrance`). |
| `/runs/[runId]` | Run progress and output detail — real-time step states and output URLs for a completed or in-flight run. |
| `/settings` | Wallet auth and BYOK provider secrets — connect a Thirdweb wallet and manage encrypted provider keys. |
## Auth Posture
Zap uses a tiered auth model designed to keep demos frictionless while protecting live spending and provider credentials.
**Public — no auth required**
* All documentation pages (`/docs`, `/quickstart`)
* The gallery and recipe detail pages
* Mock demo runs via `POST /api/zaps/run` with `"live": false`
* Skill manifest endpoints (`/api/skills`, `/api/skills/[skill]`)
**Protected — wallet-authenticated Supabase bearer token required**
* Creator live runs (`POST /api/zaps/run` with `"live": true`) — the server rejects requests without a valid bearer token before dispatching to any provider
* Provider secret management (`GET /api/secrets`, `PUT /api/secrets`, `DELETE /api/secrets`) — all mutations require the authenticated owner's JWT
**Legacy Basic Auth**
Certain provider proxy surfaces and Eve-adjacent endpoints may still be protected by HTTP Basic Auth where explicitly configured. Check your deployment environment variables if you encounter `401` responses on `/api/providers/*` routes.
## REST API Overview
Execute a recipe pipeline. Pass `"live": true` plus a bearer token to route to real providers; omit it for a zero-spend mock run.
Return the full skill manifest — recipe names, hashes, and download URLs — used by agents to bootstrap a project.
Return the list of all installed recipe specs — titles, slugs, input contracts, and step definitions — for the current deployment.
Upsert an encrypted BYOK provider key for the authenticated creator. Keys are stored in Supabase and never returned in plaintext to the browser.
Exchange a Thirdweb EIP-191 wallet signature for a Supabase Auth session token used by all subsequent API calls.
### POST /api/zaps/run
Executes a named recipe. The `slug` field maps to a file under `agent/skills/`.
```http theme={null}
POST /api/zaps/run
Content-Type: application/json
Authorization: Bearer # required only when live=true
```
```json theme={null}
{
"slug": "world-cup-entrance",
"inputs": { "teamName": "Zap FC" },
"live": false,
"extendCount": 0
}
```
**Response (mock)**
```json theme={null}
{
"mode": "mock",
"status": "done",
"spendUsd": 0,
"zapUrl": "mock://zap/world-cup-entrance/Zap.mp4"
}
```
When `live` is `true` and the token is valid, the server resolves provider keys from the caller's Supabase vault and dispatches the run to real providers.
### GET /api/skills
Returns the full skill download manifest. The `origin` of the request is used to build absolute download URLs, so agents calling from localhost get local URLs.
```http theme={null}
GET /api/skills
```
```json theme={null}
{
"generatedAt": "2025-01-15T12:00:00Z",
"version": 1,
"skills": [
{
"skill": "zap",
"hash": "abc123",
"path": "zap",
"fileCount": 3,
"downloadUrl": "https://zap.wzrd.tech/api/skills/zap",
"jsonUrl": "https://zap.wzrd.tech/api/skills/zap?format=json"
},
{
"skill": "zap-authoring",
"hash": "def456",
"path": "zap-authoring",
"fileCount": 2,
"downloadUrl": "https://zap.wzrd.tech/api/skills/zap-authoring",
"jsonUrl": "https://zap.wzrd.tech/api/skills/zap-authoring?format=json"
}
]
}
```
Individual skill content is fetched at `GET /api/skills/[skill]`. Append `?format=json` to receive a JSON envelope instead of raw Markdown.
### GET /api/zaps
Returns the list of all installed recipe specs from `agent/skills/`. Each entry is a `PublicZapSpec` — the full YAML-derived recipe definition plus a human-readable `title` field derived from the recipe slug.
```http theme={null}
GET /api/zaps
```
```json theme={null}
{
"zaps": [
{
"zap": "world-cup-entrance",
"title": "World Cup Entrance",
"description": "Generate a cinematic team entrance video.",
"version": 1,
"defaults": { "provider": "gmi" },
"budget": { "cap_usd": 2.0, "estimate_usd": 0.8 },
"inputs": {
"teamName": { "type": "string", "label": "Team Name", "required": true }
},
"output": "Zap.mp4",
"steps": []
}
]
}
```
This endpoint is unauthenticated and is used by the `/gallery` page and the `/zap/[slug]` runner to enumerate available recipes.
## Smoke Test After Deploy
Run these three checks immediately after deploying a new version to confirm the app and key API routes are up:
```bash theme={null}
curl -I https://zap.wzrd.tech/
curl -I https://zap.wzrd.tech/docs
curl -I https://zap.wzrd.tech/studio
```
All three should return `HTTP/2 200`. A non-200 on `/studio` usually indicates a missing environment variable for the Eve agent backend.