Galon Cloud
Galon API v1

集成 Galon Cloud

创建项目,签发最小权限 API 密钥,发现已授权工具,并从服务器调用 API。

快速开始

登录并创建测试项目,只授予所需权限,然后调用 GET /v1/tools、配置一项服务,并在验收测试后创建独立的 live 密钥。

export GALON_API_BASE="https://api.galon.ai"
export GALON_API_KEY="gln_test_..."

curl "$GALON_API_BASE/v1/tools"   -H "Authorization: Bearer $GALON_API_KEY"

身份验证与隔离

通过 Authorization: Bearer 请求头发送 API 密钥。每个密钥仅绑定一个租户、项目和环境。只将其保存在服务器端密钥管理器中,绝不要放入浏览器、移动应用或源代码仓库。

按服务限制的密钥

仅授予 mail:send、domain:lookup 或 build:create 等精确权限。每个应用使用一个密钥。除非确实需要全部操作,否则避免服务通配符,并立即撤销不再使用的密钥。

mail:send
domain:lookup
domain:read
build:create
build:read
artifact:read
job:read

异步任务与幂等性

变更操作返回任务。发送稳定的 Idempotency-Key:相同密钥和意图返回同一任务;相同密钥配合不同意图返回 HTTP 409。轮询任务端点,并且只重试安全或幂等请求。

POST /v1/jobs
GET  /v1/jobs/{job_id}
POST /v1/jobs/{job_id}/cancel
GET  /v1/builds/{job_id}/artifacts

发送邮件

POST /v1/emails 接收 from_email、subject、text 或 html,以及 to:一个地址或地址列表。cc 和 bcc 是可选列表;to、cc 和 bcc 合计最多 50 个不同收件人,每个收件人都计入您的配额和计费用量。每个收件人都会收到单独的副本,并附带其专属的一键退订链接,因此 bcc 收件人永远不会被公开;被抑制的收件人(退信、投诉、退订)会被跳过。attachments 是最多 10 个对象的列表,包含 filename、content(base64)和可选的 content_type;编码后的邮件必须小于 25 MB,可执行文件会被拒绝。scheduled_at(带时区的 ISO 8601,最多提前 72 小时)可延迟发送;在仍排队时,POST /v1/emails/{job_id}/cancel 可将其取消。POST /v1/emails/batch 接收 {"emails": [...]},包含 1 到 100 封不带附件的邮件;每封邮件成为独立的 job,按批次的 Idempotency-Key 及其位置保证幂等。单个收件人仍可使用 to_email。 只有批次登记是原子的(atomic=true);执行和投递彼此独立。重试必须使用完全相同的有序列表;内容、大小或顺序的任何变化都会返回 HTTP 409。

POST /v1/emails
POST /v1/emails/batch
POST /v1/emails/{job_id}/cancel

错误

HTTP 401 表示凭据无效或已过期,403 表示权限不足,409 表示幂等性或版本冲突,422 表示请求无效,503 表示暂时不可用。

机器可读参考

使用 OpenAPI 合约获取架构,使用 LLM 集成指南获取代理说明。英语是规范源;所有翻译中的路径、字段名、权限名和示例保持一致。