Inngest REST API v2
For Cloud operations, prefer available connected Inngest Cloud MCP tools. This repository does not install the upstream inngest-cloud skill.
Keep this skill for explicit terminal/HTTP work or a capability missing from
MCP. Do not ask for an API key when OAuth MCP can complete the task.
Use this skill for raw REST API v2 work and API reference lookup. If the task
can be completed through npx inngest-cli@latest api, use inngest-api-cli
instead; the CLI is safer for agents because it handles target/auth flags and
endpoint command wiring.
Prefer CLI First
Use inngest-api-cli for:
- Run and trace debugging from a run ID or event ID.
- Account, environment, key, webhook, app sync, and function invocation checks.
- Insights table/schema/query workflows.
- Local dev server or Cloud operational checks.
Use raw REST API v2 only when:
- The CLI does not expose the needed endpoint.
- The user explicitly asks for HTTP, curl, fetch, OpenAPI, or API docs.
- You need to inspect request/response schemas before deciding what to do.
Docs Lookup
When precision matters, fetch current docs instead of guessing:
- API overview:
https://api-docs.inngest.com/
- Authentication:
https://api-docs.inngest.com/authentication
- LLM index:
https://api-docs.inngest.com/llms.txt
- OpenAPI v2 spec:
https://api-docs.inngest.com/api-specs/v2.json
- Markdown page pattern: add
.md to a docs URL, for example
https://api-docs.inngest.com/v2/runs/GetFunctionTrace.md
- Endpoint request/response schemas:
references/rest-api-v2.md
If a Markdown page returns an error or omits generated reference details, use
the OpenAPI spec for methods, paths, parameters, request bodies, and schemas.
Base URLs
- Cloud v2:
https://api.inngest.com/v2
- Local dev server v2:
http://localhost:8288/api/v2
- API docs say the dev server may also be reached through the local server
origin. Confirm the actual dev server port before making local requests.
Authentication
The REST API uses Bearer token authentication.
- Prefer
INNGEST_API_KEY for requests from CI, scripts, tools, and agents.
- Signing keys are primarily for apps communicating with Inngest; use them for
API requests only when that is the available, appropriate credential.
- API keys are for v2 endpoints only.
- Include
X-Inngest-Env or use an environment-scoped API key when operating
outside the default production environment.
- Never paste, print, commit, or log API keys, event keys, signing keys,
webhook URLs, or decrypted secrets.
Example:
curl -fsSL \
-H "Authorization: Bearer $INNGEST_API_KEY" \
-H "X-Inngest-Env: $INNGEST_ENV" \
https://api.inngest.com/v2/account
Endpoint Discovery
Use the OpenAPI spec as the source of truth:
curl -fsSL https://api-docs.inngest.com/api-specs/v2.json
Current v2 areas include account, environments, keys, webhooks, apps, function
invocation, event-run lookup, function runs, traces, Insights, and partner APIs.
Endpoint coverage can change, so inspect the spec before writing a raw request.
For API-only or access-gated endpoints, such as partner-account endpoints,
confirm the user has the needed access before attempting a call.
Request Rules
- Derive method, path, query params, headers, and body from OpenAPI.
- Do not invent undocumented request fields.
- Use structured JSON parsing before making decisions from responses.
- Use body files or here-docs for complex JSON instead of shell-escaped one
liners.
- Add pagination cursors when
page.hasMore is true and complete results are
needed.
- Treat missing
data in list responses as an empty list unless an error is
present.
Mutation Safety
Read before write. Confirm target account, environment, resource, and intent
before raw HTTP mutations unless the user's instruction already makes all of
that explicit.
Treat these categories as mutating or side-effecting:
- Creating or patching environments.
- Creating webhooks.
- Syncing apps.
- Invoking functions.
- Partner account creation.
- Broad Insights queries that may be expensive or noisy.
Output Handling
- Summarize IDs, names, statuses, pagination, and actionable errors.
- Redact token values, webhook URLs, sensitive payload fields, and decrypted
secrets.
- Do not paste large raw traces, full OpenAPI fragments, or full response
bodies unless the user asks.
- If auth fails, first verify that a credential is present in the environment;
then ask the user to provide or rotate
INNGEST_API_KEY without pasting it
into chat.
This Repository
These upstream Inngest instructions are vendored for agent tooling and
integration work in this monorepo.
Repository Triggers
Use this skill when inngest-api matches the current Inngest task. If the
right skill is unclear, start with docs/ai/skills/inngest/SKILL.md.
Repository Workflow
- Confirm whether the request is agent-tooling guidance or product runtime
integration.
- Use
inngest-brownfield-audit before changing existing app workflows or
fragile background work.
- Follow this upstream guidance under OpenSpec, root
AGENTS.md, repo
rulebooks, framework docs, and runtime evidence.
- Keep runtime packages, app code, migrations, and
INNGEST_* env
requirements out of agent-tooling-only changes.
Repository Checklist
1---2name: inngest-api3description: >-4 Use when the user explicitly asks for the Inngest REST API v2, raw HTTP,5 OpenAPI, API docs, API authentication, or an endpoint that the Inngest CLI6 does not expose. Covers api-docs.inngest.com, llms.txt, the OpenAPI v2 spec,7 Bearer authentication with API keys or signing keys, production and local8 base URLs, raw curl/fetch requests, request-shape discovery, pagination,9 secret redaction, and when to prefer the `inngest-api-cli` skill instead.10metadata:11 source: https://skillmd.com/skills/asymmetric-al/inngest-api12---1314# Inngest REST API v21516For Cloud operations, prefer available connected Inngest Cloud MCP tools. This repository does not install the upstream inngest-cloud skill.17Keep this skill for explicit terminal/HTTP work or a capability missing from18MCP. Do not ask for an API key when OAuth MCP can complete the task.1920Use this skill for raw REST API v2 work and API reference lookup. If the task21can be completed through `npx inngest-cli@latest api`, use `inngest-api-cli`22instead; the CLI is safer for agents because it handles target/auth flags and23endpoint command wiring.2425## Prefer CLI First2627Use `inngest-api-cli` for:2829- Run and trace debugging from a run ID or event ID.30- Account, environment, key, webhook, app sync, and function invocation checks.31- Insights table/schema/query workflows.32- Local dev server or Cloud operational checks.3334Use raw REST API v2 only when:3536- The CLI does not expose the needed endpoint.37- The user explicitly asks for HTTP, curl, fetch, OpenAPI, or API docs.38- You need to inspect request/response schemas before deciding what to do.3940## Docs Lookup4142When precision matters, fetch current docs instead of guessing:4344- API overview: `https://api-docs.inngest.com/`45- Authentication: `https://api-docs.inngest.com/authentication`46- LLM index: `https://api-docs.inngest.com/llms.txt`47- OpenAPI v2 spec: `https://api-docs.inngest.com/api-specs/v2.json`48- Markdown page pattern: add `.md` to a docs URL, for example49 `https://api-docs.inngest.com/v2/runs/GetFunctionTrace.md`50- Endpoint request/response schemas:51 [references/rest-api-v2.md](references/rest-api-v2.md)5253If a Markdown page returns an error or omits generated reference details, use54the OpenAPI spec for methods, paths, parameters, request bodies, and schemas.5556## Base URLs5758- Cloud v2: `https://api.inngest.com/v2`59- Local dev server v2: `http://localhost:8288/api/v2`60- API docs say the dev server may also be reached through the local server61 origin. Confirm the actual dev server port before making local requests.6263## Authentication6465The REST API uses Bearer token authentication.6667- Prefer `INNGEST_API_KEY` for requests from CI, scripts, tools, and agents.68- Signing keys are primarily for apps communicating with Inngest; use them for69 API requests only when that is the available, appropriate credential.70- API keys are for v2 endpoints only.71- Include `X-Inngest-Env` or use an environment-scoped API key when operating72 outside the default production environment.73- Never paste, print, commit, or log API keys, event keys, signing keys,74 webhook URLs, or decrypted secrets.7576Example:7778```bash79curl -fsSL \80 -H "Authorization: Bearer $INNGEST_API_KEY" \81 -H "X-Inngest-Env: $INNGEST_ENV" \82 https://api.inngest.com/v2/account83```8485## Endpoint Discovery8687Use the OpenAPI spec as the source of truth:8889```bash90curl -fsSL https://api-docs.inngest.com/api-specs/v2.json91```9293Current v2 areas include account, environments, keys, webhooks, apps, function94invocation, event-run lookup, function runs, traces, Insights, and partner APIs.95Endpoint coverage can change, so inspect the spec before writing a raw request.9697For API-only or access-gated endpoints, such as partner-account endpoints,98confirm the user has the needed access before attempting a call.99100## Request Rules101102- Derive method, path, query params, headers, and body from OpenAPI.103- Do not invent undocumented request fields.104- Use structured JSON parsing before making decisions from responses.105- Use body files or here-docs for complex JSON instead of shell-escaped one106 liners.107- Add pagination cursors when `page.hasMore` is true and complete results are108 needed.109- Treat missing `data` in list responses as an empty list unless an error is110 present.111112## Mutation Safety113114Read before write. Confirm target account, environment, resource, and intent115before raw HTTP mutations unless the user's instruction already makes all of116that explicit.117118Treat these categories as mutating or side-effecting:119120- Creating or patching environments.121- Creating webhooks.122- Syncing apps.123- Invoking functions.124- Partner account creation.125- Broad Insights queries that may be expensive or noisy.126127## Output Handling128129- Summarize IDs, names, statuses, pagination, and actionable errors.130- Redact token values, webhook URLs, sensitive payload fields, and decrypted131 secrets.132- Do not paste large raw traces, full OpenAPI fragments, or full response133 bodies unless the user asks.134- If auth fails, first verify that a credential is present in the environment;135 then ask the user to provide or rotate `INNGEST_API_KEY` without pasting it136 into chat.137138## This Repository139140These upstream Inngest instructions are vendored for agent tooling and141integration work in this monorepo.142143## Repository Triggers144145Use this skill when `inngest-api` matches the current Inngest task. If the146right skill is unclear, start with `docs/ai/skills/inngest/SKILL.md`.147148## Repository Workflow1491501. Confirm whether the request is agent-tooling guidance or product runtime151 integration.1522. Use `inngest-brownfield-audit` before changing existing app workflows or153 fragile background work.1543. Follow this upstream guidance under OpenSpec, root `AGENTS.md`, repo155 rulebooks, framework docs, and runtime evidence.1564. Keep runtime packages, app code, migrations, and `INNGEST_*` env157 requirements out of agent-tooling-only changes.158159## Repository Checklist160161- [ ] The task has explicit product-runtime scope before adding Inngest app code162 or dependencies.163- [ ] Existing workflows were audited before introducing or changing durable164 workflow behavior.165- [ ] Local dev-server MCP usage is backed by a running Inngest dev server on the configured166 port.167- [ ] Upstream source and license attribution remain documented in168 `docs/ai/skills/inngest/references/upstream.md`.