Inngest Api

Inngest REST API v2

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.

Inngest v2 REST API Reference

Condensed from the official OpenAPI spec (v2.0.0). The live spec is always authoritative and machine-readable: https://api-docs.inngest.com/api-specs/v2.json. Human docs: https://api-docs.inngest.com/ (append .md to any page URL for markdown; index at /llms.txt).

Base URLs

Authentication

Authorization: Bearer <key> on every request (the local dev server requires no key).

Environment targeting for non-production Cloud environments: X-Inngest-Env: <env-name> header. Required for the webhook endpoints; optional filter for key listings.

Conventions

• Success envelope: {"data": <payload>, "metadata": {"fetchedAt": <ts>, "cachedUntil": <ts|null>}}
• List envelope: adds "page": {"cursor": <string>, "hasMore": <bool>, "limit": <int>} — pass cursor as a query param to fetch the next page until hasMore is false.
• Error envelope: {"errors": [{"code": <string>, "message": <string>}]}
• Common statuses: 401 unauthorized, 403 insufficient permissions, 404 not found, 409 conflict/idempotency, 422 business-logic rejection (rate limited, debounced, skipped, sync failed), 429 API rate limit exceeded, 500 server error.
• IDs for runs and events are ULIDs (e.g., 01KTCTWT8XDEGWDMVX3Q9M69ND).

Enums

---

Runs

GET /runs/{runId} — Get function run

Canonical run summary.

• Path: runId (required)
• Query: includeOutput (bool)

Response data:

id, status, queuedAt, startedAt, endedAt, durationMs,
app: { id },
function: { id, name },
trigger: { eventName, eventIds[], isBatch, batchId, cronSchedule },
output (when includeOutput=true)

GET /runs/{runId}/trace — Get function trace

Trace tree for a run. The root span represents the function; children are the steps.

• Path: runId (required)
• Query: includeOutput (bool — include step inputs/outputs)

Response data:

runId,
rootSpan: {
  id, name, status, stepId, stepOp,
  queuedAt, startedAt, endedAt, durationMs,
  input, output,
  metadata: [{ kind, scope, updatedAt, values }],
  children: [ <same span shape, recursive> ]
}

Find the failure: filter rootSpan.children[] (and nested children) for status == "FAILED" and read output.

GET /events/{eventId}/runs — Get event runs

Runs triggered by an event. Paginated.

• Path: eventId (required)
• Query: includeOutput (bool), limit (1–40), cursor

Response data: array of run summaries (same shape as GET /runs/{runId}).

Functions

POST /apps/{appId}/functions/{functionId}/invoke — Invoke function

• Path: appId, functionId (required) — these are the IDs from your code (client id, createFunction id)
• Body:

{ "data": { ... }, "idempotencyKey": "optional-string" }

Responses:

• 201 — completed synchronously. data: runId, queuedAt, startedAt, completedAt, result (JSON string), error.
• 202 — enqueued asynchronously. Same shape; poll GET /runs/{runId}.
• 409 — idempotency key already used. 422 — rejected by flow control (rate limit, debounce, skip). 429 — API rate limit, request not executed.

Apps

POST /apps/{appId}/syncs — Sync app

Sync an app at the provided serve URL (e.g., after a deploy).

• Path: appId (required)
• Body: { "url": "https://myapp.com/api/inngest" }

Response data: id, appId, status, error: { code, message }. A 422 still returns this shape with error populated — the sync was attempted and failed.

Environments

GET /envs — List environments

• Query: limit (1–250), cursor
• Response data: array of { id, name, type (PRODUCTION|TEST|BRANCH), isArchived, createdAt }

POST /envs — Create environment

• Body: { "id": "...", "name": "..." }
• Response 201 with the created environment.

PATCH /envs/{id} — Update environment

• Path: id (required)
• Body: { "isArchived": true|false } (only provided fields are modified)

Webhooks

Both require the X-Inngest-Env header.

GET /env/webhooks — List webhooks

• Query: limit (1–100), cursor
• Response data: array of { id, name, url, environment, transform, response, eventFilter: { events[], filter (ALLOW|DENY) }, createdAt, updatedAt }

POST /env/webhooks — Create webhook

• Body:

{
  "name": "descriptive name",
  "transform": "inline JS transform for incoming events",
  "response": "optional inline JS answering GET requests",
  "eventFilter": { "events": ["..."], "filter": "ALLOW" }
}

• 201 with the created webhook (including its url). 409 if a webhook with the same URL exists.

Keys

GET /keys/events — List account event keys

GET /keys/signing — List account signing keys

• Query: limit (1–100), cursor
• Header: X-Inngest-Env (optional — defaults to production keys)
• Response data: array of { id, name, key, environment, createdAt }

These return key material. Treat output as secret; don't echo into logs.

Account

GET /account — Get account

Response data: { id, name, email, createdAt, updatedAt }. Useful as an auth smoke test for Cloud keys.

Partner API

For partners managing sub-accounts only.

GET /partner/accounts — List partner accounts

• Query: limit (1–1000), cursor

POST /partner/accounts — Create partner account

• Body: { "name": "...", "email": "..." }
• Response 201 includes the new sub-account's apiKey.

Insights

Newer than the published OpenAPI spec; documented from the CLI. See cli-commands.md.

Health

GET /health

{"data": {"status": "ok"}} — reachability probe, no auth required on the dev server.

---

v1 API (still available)

v1 lives at https://api.inngest.com/v1 (signing-key auth) and covers surfaces v2 doesn't yet: listing events, fetching a single event, cancelling a run, bulk cancellations (create/list/delete), run jobs, resuming signals, and webhook get/update/delete. When v2 lacks an operation, check the v1 docs at https://api-docs.inngest.com/v1 before declaring it impossible.