truto-api-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Truto API Conventions

Truto API 约定

Skill Routing

技能路由

This plugin has two skills with distinct roles:

Truto skill — Use when writing code in the user's project that calls
```
api.truto.one
```
. This produces application code:
```
fetch()
```
calls, webhook handlers, connection flows.
Truto CLI skill — Use when running terminal commands to set up, explore, or debug. This runs
```
truto
```
CLI commands in the shell for admin tasks, one-time data access, and troubleshooting. Nothing the CLI does belongs in the user's codebase.

该插件包含两个职责不同的技能：

Truto 技能 —— 在用户项目中编写调用
```
api.truto.one
```
的代码时使用。用于生成应用代码：
```
fetch()
```
调用、Webhook 处理器、连接流程。
Truto CLI 技能 —— 在运行终端命令进行设置、探索或调试时使用。通过 shell 执行
```
truto
```
CLI 命令来完成管理任务、一次性数据访问和故障排查。CLI 执行的操作均不属于用户代码库范畴。

Base URL

基础 URL

https://api.truto.one

https://api.truto.one

Authentication

认证

All API requests require a Bearer token in the

Authorization

header:

Authorization: Bearer <api_token>

API tokens are scoped to a single environment. When using an API token, operations that require an

environment_id

are automatically scoped to the token's environment.

所有 API 请求都需要在

Authorization

头中携带 Bearer 令牌：

Authorization: Bearer <api_token>

API 令牌仅作用于单个环境。使用 API 令牌时，需要

environment_id

的操作会自动限定在该令牌对应的环境中。

Content-Type

内容类型

JSON requests:
```
Content-Type: application/json
```
File uploads:
```
Content-Type: multipart/form-data
```
Workflows also accept
```
Content-Type: application/yaml
```

JSON 请求：
```
Content-Type: application/json
```
文件上传：
```
Content-Type: multipart/form-data
```
工作流还支持
```
Content-Type: application/yaml
```

Unified API URL Pattern

统一 API URL 模式

https://api.truto.one/unified/{model_name}/{resource_name}

List:

GET /unified/{model}/{resource}?integrated_account_id={id}

Get:

GET /unified/{model}/{resource}/{id}?integrated_account_id={id}

Create:

POST /unified/{model}/{resource}?integrated_account_id={id}

Update:

PATCH /unified/{model}/{resource}/{id}?integrated_account_id={id}

Delete:

DELETE /unified/{model}/{resource}/{id}?integrated_account_id={id}

Custom method:

POST /unified/{model}/{resource}/{method_name}?integrated_account_id={id}

The

integrated_account_id

query parameter is required on all unified, proxy, and custom API calls.

https://api.truto.one/unified/{model_name}/{resource_name}

列表查询：

GET /unified/{model}/{resource}?integrated_account_id={id}

详情查询：

GET /unified/{model}/{resource}/{id}?integrated_account_id={id}

创建：

POST /unified/{model}/{resource}?integrated_account_id={id}

更新：

PATCH /unified/{model}/{resource}/{id}?integrated_account_id={id}

删除：

DELETE /unified/{model}/{resource}/{id}?integrated_account_id={id}

自定义方法：

POST /unified/{model}/{resource}/{method_name}?integrated_account_id={id}

integrated_account_id

查询参数在所有统一、代理和自定义 API 调用中都是必填项。

Proxy API URL Pattern

代理 API URL 模式

https://api.truto.one/proxy/{resource}?integrated_account_id={id}

Pass-through to the native API of the integrated tool. Same HTTP methods as unified.

https://api.truto.one/proxy/{resource}?integrated_account_id={id}

直接转发至集成工具的原生 API。支持与统一 API 相同的 HTTP 方法。

Custom API URL Pattern

自定义 API URL 模式

https://api.truto.one/custom/{path}?integrated_account_id={id}

Any HTTP method; the path after

/custom/

is forwarded to the integration's custom handler.

https://api.truto.one/custom/{path}?integrated_account_id={id}

支持任意 HTTP 方法；

/custom/

之后的路径会转发至集成的自定义处理器。

Pagination

分页

List endpoints return cursor-based pagination:

json

{
  "result": [...],
  "next_cursor": "cursor_value_or_null",
  "prev_cursor": "cursor_value_or_null"
}

Pass

next_cursor

as a query parameter to fetch the next page. When

next_cursor

null

, there are no more pages.

列表端点返回基于游标的分页结果：

json

{
  "result": [...],
  "next_cursor": "cursor_value_or_null",
  "prev_cursor": "cursor_value_or_null"
}

将

next_cursor

作为查询参数传入即可获取下一页数据。当

next_cursor

为

null

时，表示没有更多数据页。

Idempotency

幂等性

Mutating unified/proxy/custom API calls support idempotency via the

Idempotency-Key

header:

Idempotency-Key: <unique_key>

统一/代理/自定义 API 的变更调用支持通过

Idempotency-Key

头实现幂等性：

Idempotency-Key: <unique_key>

Admin API Pagination

管理员 API 分页

Admin endpoints (listing integrations, accounts, sync jobs, etc.) use the same cursor pattern. Filter parameters use structured query syntax:

field[operator]=value

(e.g.,

id[in]=uuid1,uuid2

管理员端点（列出集成、账户、同步任务等）使用相同的游标分页模式。过滤参数采用结构化查询语法：

field[operator]=value

（例如：

id[in]=uuid1,uuid2

）。