API 概览与认证

Ody REST API 位于 https://api.ody.co/v1/api，并通过作为 Bearer 令牌发送的 API 密钥对每个请求进行认证——在设置 → 开发者 API 中创建一个，然后调用以下端点。

认证

在每个请求的 Authorization 标头中发送您的密钥：

curl https://api.ody.co/v1/api/contacts \
  -H "Authorization: Bearer ody_live_…"

• 密钥有两种模式：ody_live_… 密钥是实时密钥，ody_test_… 密钥行为相同，但消息发送是模拟的（记录为 deliveryStatus: "simulated"，从不传输）。请参阅使用测试模式安全构建。
• 缺少、无效或已撤销的密钥将返回 401 unauthenticated。
• 当密钥调用其授权范围之外的端点时，受范围限制的密钥将返回 403 permission_denied——并指出缺失的范围。
• 每个调用都以创建密钥的成员的权限运行，且仅限于该工作区内。

端点

方法与路径	功能	所需范围
GET /v1/api/contacts	列出或搜索联系人（?q=, 分页）	contacts:read
POST /v1/api/contacts	创建联系人	contacts:write
GET /v1/api/contacts/:id	获取联系人完整详情	contacts:read
PATCH /v1/api/contacts/:id	更新联系人（仅更改提供的字段）	contacts:write
DELETE /v1/api/contacts/:id	删除联系人	contacts:write
GET /v1/api/conversations	列出对话（`?status=open	done`, 分页）
GET /v1/api/conversations/:id	获取完整对话串	conversations:read
PATCH /v1/api/conversations/:id	设置状态 — 请求体 {"status":"open"} 或 {"status":"done"}	conversations:write
POST /v1/api/messages	发送 SMS/MMS（支持 Idempotency-Key）	messages:send
GET /v1/api/messages/search	搜索消息正文和转录（?q=）	conversations:read
GET /v1/api/calls	列出通话和语音邮件历史记录	conversations:read
POST /v1/api/calls	拨打外呼 AI 电话 — 您的已发布代理拨号	calls:place
GET /v1/api/numbers	列出您工作区的号码	numbers:read
GET /v1/api/numbers/available	搜索可购买的号码（?country=, ?startsWith=, ?contains=, ?locality=, ?state=, ?limit=）	numbers:manage
POST /v1/api/numbers	购买号码 — 按应用内购买计费（支持 Idempotency-Key）	numbers:manage
POST /v1/api/numbers/:e164/connect and …/disconnect	将号码路由到或从您的 AI 代理移除	agent:manage
GET /v1/api/messaging	10DLC 注册状态（step, canText）	numbers:manage
POST /v1/api/messaging/registration	提交您的 10DLC 业务 + 活动（计费）	numbers:manage
POST /v1/api/messaging/refresh	重新检查并推进 10DLC 运营商审核	numbers:manage
GET/PATCH /v1/api/agent	读取或更新您的 AI 代理配置（草稿）	agent:manage
POST /v1/api/agent/publish	发布您的代理配置	agent:manage
GET /v1/api/webhook-events	列出可订阅的 Webhook 事件类型	webhooks:manage
GET/POST /v1/api/webhooks and /v1/api/webhooks/:id…	管理外呼 Webhook 端点	webhooks:manage
GET /v1/api/openapi.json	OpenAPI 3.1 规范	none

列表端点通过 ?limit= 和 ?cursor= 进行分页——请参阅分页、幂等性和错误处理。

联系人

POST /v1/api/contacts 需要至少一个身份字段：firstName、lastName、company、电话或电子邮件。电话和电子邮件接受简单字符串（"phone": "+15125550123"）或完整的带标签数组（"phones": [{"value": "+15125550123", "label": "work"}]）。在 PATCH 请求中，只有您提供的字段会更改；phones、emails、notes、properties 和 tags 在提供时会被整体替换。

发送消息

POST /v1/api/messages 接受现有的 conversationId 或 to 中的收件人电话号码（E.164 格式）。使用 to 时，Ody 会选择您工作区的发送号码（或尊重您拥有的 from 号码），如果需要则创建对话，并串联消息。为 MMS 添加最多 10 个可公开获取的 mediaUrls：

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

没有活跃电话号码的工作区将收到 409 failed_precondition。在 24 小时内使用相同的 Idempotency-Key 重试将重播第一个响应，而不是重复发送。

号码、短信、AI 呼叫和您的代理

API 还可以端到端地运行电话线路：搜索和购买号码、注册 10DLC 短信、配置和发布您的 AI 代理、将号码路由到它，以及拨打外呼 AI 电话。这些端点使用它们自己的三个范围——numbers:manage（购买号码和 10DLC）、calls:place（拨打 AI 电话）和 agent:manage（管理 AI 代理）——它们所做的一切都将准确地反映在您的账户中，就像您在应用程序中操作一样，具有相同的计费和规则。请参阅通过 API 购买号码和注册短信和通过 API 拨打 AI 电话和管理 Astra。

错误、请求 ID 和速率限制

每个错误都使用统一的封装，并且每个响应（成功或错误）都带有 X-Request-Id 标头——在联系支持时请引用它：

{ "error": { "code": "not_found", "message": "Contact not found", "requestId": "req_…" } }

每个密钥每分钟可获得 600 个请求，并带有标准 RateLimit-* 标头。详情请参阅 API 速率限制和最佳实践 和 分页、幂等性和错误处理。

相关文章

• 获取您的 Ody API 密钥
• 接收 Webhook 并验证签名
• 分页、幂等性和错误处理
• SDK 快速入门：TypeScript 和 Python