inngest-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

本技能适用于原生REST API v2操作及API参考查询。如果任务可通过

npx inngest-cli@latest api

完成，请优先使用

inngest-api-cli

；CLI对Agent更安全，因为它会处理目标/认证标志和端点命令连接。

Prefer CLI First

优先使用CLI

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.

以下场景使用

inngest-api-cli

：

通过运行ID或事件ID进行运行和追踪调试。
账户、环境、密钥、Webhook、应用同步及函数调用检查。
Insights表格/ schema/查询工作流。
本地开发服务器或云端运维检查。

仅在以下场景使用原生REST API v2：

CLI未暴露所需端点。
用户明确要求HTTP、curl、fetch、OpenAPI或API文档。
需要先检查请求/响应schema再决定操作。

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.

当需要精准信息时，请获取最新文档而非猜测：

API概览：
```
https://api-docs.inngest.com/
```

认证：

https://api-docs.inngest.com/authentication

LLM索引：
```
https://api-docs.inngest.com/llms.txt
```

OpenAPI v2规范：

https://api-docs.inngest.com/api-specs/v2.json

Markdown页面规则：在文档URL后添加

.md

，例如

https://api-docs.inngest.com/v2/runs/GetFunctionTrace.md

端点请求/响应schema：references/rest-api-v2.md

如果Markdown页面返回错误或缺失生成的参考细节，请使用OpenAPI规范获取方法、路径、参数、请求体及schema。

Base URLs

基础URL

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.

云端v2：
```
https://api.inngest.com/v2
```
本地开发服务器v2：
```
http://localhost:8288/api/v2
```
API文档说明开发服务器也可通过本地服务器源访问。发起本地请求前请确认实际开发服务器端口。

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:

bash

curl -fsSL \
  -H "Authorization: Bearer $INNGEST_API_KEY" \
  -H "X-Inngest-Env: $INNGEST_ENV" \
  https://api.inngest.com/v2/account

REST API使用Bearer令牌认证。

对于CI、脚本、工具及Agent发起的请求，优先使用
```
INNGEST_API_KEY
```
。
签名密钥主要用于与Inngest通信的应用；仅当这是可用且合适的凭证时，才将其用于API请求。
API密钥仅适用于v2端点。
在默认生产环境外操作时，请添加
```
X-Inngest-Env
```
头或使用环境范围的API密钥。
切勿粘贴、打印、提交或记录API密钥、事件密钥、签名密钥、Webhook URL或解密后的敏感信息。

示例：

bash

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:

bash

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.

请以OpenAPI规范为事实来源：

bash

curl -fsSL https://api-docs.inngest.com/api-specs/v2.json

当前v2涵盖的领域包括账户、环境、密钥、Webhook、应用、函数调用、事件运行查询、函数运行、追踪、Insights及合作伙伴API。端点覆盖范围可能变化，因此在编写原生请求前请检查规范。

对于仅API可用或需要权限的端点（如合作伙伴账户端点），在尝试调用前请确认用户拥有所需权限。

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.

从OpenAPI获取方法、路径、查询参数、头信息及请求体。
不要自行添加未记录的请求字段。
在根据响应做决策前，先使用结构化JSON解析。
对于复杂JSON，使用体文件或here-docs替代shell转义的单行命令。
当
```
page.hasMore
```
为true且需要完整结果时，添加分页游标。
除非存在错误，否则将列表响应中缺失的
```
data
```
视为空列表。

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.

先读再写。在发起原生HTTP变更前，请确认目标账户、环境、资源及意图，除非用户的指令已明确所有这些信息。

将以下类别视为具有变更性或副作用的操作：

创建或更新环境。
创建Webhook。
同步应用。
调用函数。
创建合作伙伴账户。
可能产生高额成本或大量数据的宽泛Insights查询。

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.

总结ID、名称、状态、分页及可操作错误。
脱敏令牌值、Webhook URL、敏感负载字段及解密后的敏感信息。
除非用户要求，否则不要粘贴大型原生追踪信息、完整OpenAPI片段或完整响应体。
如果认证失败，请先验证环境中是否存在凭证；然后请用户提供或轮换
```
INNGEST_API_KEY
```
，不要让用户将其粘贴到聊天中。