浏览文档
API 参考文档
Management API 参考文档
浏览账户、密钥、计费和任务端点。每个端点均列出自身的身份验证和访问要求。
使用 API Key 读取账户
管理 API 地址为 https://api.flashdata.dev/v2。以下免费读取返回当前 Key 与账户的标识及归属信息。先设置 FLASHDATA_API_KEY,再执行命令。
curl --fail-with-body --silent --show-error --max-time 20 \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}" \
'https://api.flashdata.dev/v2/api-access/identity'成功时返回 HTTP 200。每个端点的认证要求以其 Authentication 字段为准:dataApiKey 使用 X-API-Key;cookieSession 使用已登录的浏览器会话。 身份响应结构
下载客户 OpenAPI 规范,涵盖查询、任务、账户、API Key 及账单。
身份验证方案
| 协议 | 要求 |
|---|---|
dataApiKey |
FlashData API 密钥。任务访问受该密钥的数据源权限范围限制。 |
cookieSession |
不透明的 Web 会话。浏览器无法读取此 Cookie。 |
csrfToken |
apiKey |
agentRegistrationProof | 发送前必须持久保存使用安全随机算法生成的 32 字节 base64url 凭证及确切请求;恢复时只能复用相同凭证与正文。此凭证不是 OAuth 令牌。 |
agentSetupCredential | 临时设置凭据,仅用于读取状态和创建认领。不是 Data API 密钥。 |
agentHandoffProof | 用于恢复所有者密钥并确认安装的凭证,绝不发送到数据查询。 |
agentIdentityKey | 普通 FlashData API Key,仅在智能体身份验证端点使用 Authorization Bearer。数据查询使用 X-API-Key。 |
系统
GET/health
服务健康状况
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 正常
200 响应 · application/json
{
"$ref": "#/components/schemas/Health"
}GET/status
读取公开的组件状态摘要
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 公开状态摘要
请求头: Cache-Control
200 响应 · application/json
{
"$ref": "#/components/schemas/PublicStatus"
}身份验证
GET/oauth/requests/{requestId}
读取应用授权请求,并将其绑定到当前会话
需要完整会话。请求在十分钟后过期。响应不允许缓存。
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
requestId · path · 必填
结构定义
{
"type": "string",
"pattern": "^fdo_[A-Za-z0-9_-]{43}$"
}响应
200 应用请求的权限
200 响应 · application/json
{
"$ref": "#/components/schemas/OAuthConsent"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求已过期、已使用或已绑定到其他会话
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/oauth/requests/{requestId}
批准或拒绝应用授权请求
需要完整会话、CSRF 验证及允许的 Origin。请求只能使用一次。响应不允许缓存。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
requestId · path · 必填
结构定义
{
"type": "string",
"pattern": "^fdo_[A-Za-z0-9_-]{43}$"
}请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"decision"
],
"properties": {
"decision": {
"type": "string",
"enum": [
"approve",
"deny"
]
}
}
}响应
200 返回已注册的客户端回调,附带授权码或拒绝结果、state 和 issuer
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"redirectUrl"
],
"properties": {
"redirectUrl": {
"type": "string",
"format": "uri"
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 授权请求不可用;请重新发起连接
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/register
创建待激活的 FlashData 账户
提交的服务条款和隐私政策版本必须与当前已发布的法律文档包一致。
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"$ref": "#/components/schemas/RegisterRequest"
}响应
201 账户已创建;需要验证邮箱
请求头: Cache-Control, X-Request-Id
201 响应 · application/json
{
"$ref": "#/components/schemas/RegisterResponse"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 超出请求速率、并发数、批量请求大小或待处理任务数量限制
请求头: Retry-After
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 发生意外内部错误
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/login
创建不透明的 Web 会话
设置具有 Secure、HttpOnly 属性的 __Host-fd_session Cookie。未验证账户获得短期 email_verification Session,只能查看验证仪表盘。符合条件的已验证账户在登录时自动获得尚未领取的一次试用额度。活跃账户获得完整 Session;需要接受法律条款的账户获得 legal_acceptance Session,已安排删除的账户获得 deletion_recovery Session。删除状态为处理中、失败或已完成的账户,以及被暂停的账户,均会收到 403。
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"$ref": "#/components/schemas/LoginRequest"
}响应
200 已通过身份验证
请求头: Set-Cookie, Cache-Control, X-Request-Id
200 响应 · application/json
{
"$ref": "#/components/schemas/LoginResponse"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 禁止登录;Problem.code 为 email_not_verified、account_suspended、account_deletion_processing、account_deletion_failed 或 account_deleted
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}423 账户暂时锁定
请求头: Retry-After
423 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 超出请求速率、并发数、批量请求大小或待处理任务数量限制
请求头: Retry-After
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/logout
撤销当前会话
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
204 会话已撤销,Cookie 已清除
请求头: Set-Cookie, Cache-Control, X-Request-Id
401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/auth/me
读取当前账户和用户
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 当前账户
请求头: Cache-Control, X-Request-Id
200 响应 · application/json
{
"$ref": "#/components/schemas/Account"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/auth/csrf
获取绑定到当前会话的 CSRF 令牌
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 CSRF 令牌
请求头: Cache-Control, X-Request-Id
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"csrfToken"
],
"properties": {
"csrfToken": {
"type": "string",
"minLength": 32,
"readOnly": true
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/email-verifications
请求发送或重新发送邮箱验证邮件
对于每个语法有效的邮箱地址,无论账户不存在、待激活、已激活、已停用还是已删除,都会返回相同响应。符合条件的待激活账户会在重发冷却时间结束后收到轮换后的一次性链接。
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 320
}
}
}响应
202 请求已接纳。响应不会透露账户是否存在。
请求头: Cache-Control, X-Request-Id
202 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"accepted"
],
"properties": {
"accepted": {
"type": "boolean",
"const": true
}
}
}422 匿名身份验证请求未通过验证
请求头: Cache-Control, X-Request-Id
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 超出匿名身份验证速率限制
请求头: Cache-Control, Retry-After, X-Request-Id
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 匿名身份验证发生意外错误
请求头: Cache-Control, X-Request-Id
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 匿名身份验证依赖项暂时不可用
请求头: Cache-Control, X-Request-Id
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/email-verifications/confirm
验证邮箱并激活账户
原子消费一次性令牌并激活账户和用户。适用现有账户与试用积分规则。没有注册会话时,用户需显式登录。来源获准且携带匹配注册会话及其 X-CSRF-Token 的请求,可获得同一已验证账户的新会话 Cookie;单独的验证令牌绝不会使用户登录。
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"$ref": "#/components/schemas/TokenRequest"
}响应
200 账户已激活
请求头: Set-Cookie, Cache-Control, X-Request-Id
200 响应 · application/json
{
"allOf": [
{
"$ref": "#/components/schemas/Account"
},
{
"type": "object",
"properties": {
"status": {
"const": "active"
},
"emailVerified": {
"const": true
}
}
}
]
}410 一次性令牌无效、已过期、已作废、已使用,或在并发确认竞争中未成功。Problem.code 为 `token_unavailable`。
请求头: Cache-Control, X-Request-Id
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 匿名身份验证请求未通过验证
请求头: Cache-Control, X-Request-Id
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 超出匿名身份验证速率限制
请求头: Cache-Control, Retry-After, X-Request-Id
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 匿名身份验证发生意外错误
请求头: Cache-Control, X-Request-Id
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 匿名身份验证依赖项暂时不可用
请求头: Cache-Control, X-Request-Id
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/email-verifications/session
邮箱验证后继续原始注册会话
需要获准的 Origin,以及与有效、经密码验证的邮箱验证会话绑定的 CSRF 令牌。在该会话所属账户验证前返回等待状态,包括在另一浏览器完成验证的情况。原子撤销注册会话,并签发新的完整会话或条款接受会话。不接受账户 ID、邮箱、密码或验证令牌,不绕过条款接受,也不发放积分。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false
}响应
200 注册会话已轮换
请求头: Set-Cookie, Cache-Control
200 响应 · application/json
{
"$ref": "#/components/schemas/LoginResponse"
}202 正在等待邮箱验证,未签发新会话
请求头: Cache-Control
202 响应 · application/json
{
"type": "object",
"required": [
"pending"
],
"additionalProperties": false,
"properties": {
"pending": {
"type": "boolean",
"const": true
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 发生意外内部错误
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/password-resets
请求发送密码重置邮件
对于语法有效的邮箱地址,无论账户是否存在或处于何种生命周期状态,始终返回相同的 202 响应。只有符合条件且处于激活或锁定状态的身份会收到邮件。
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 320
}
}
}响应
202 请求已接纳。响应不会透露账户是否存在。
请求头: Cache-Control, X-Request-Id
202 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"accepted"
],
"properties": {
"accepted": {
"type": "boolean",
"const": true
}
}
}422 匿名身份验证请求未通过验证
请求头: Cache-Control, X-Request-Id
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 超出匿名身份验证速率限制
请求头: Cache-Control, Retry-After, X-Request-Id
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 匿名身份验证发生意外错误
请求头: Cache-Control, X-Request-Id
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 匿名身份验证依赖项暂时不可用
请求头: Cache-Control, X-Request-Id
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/password-resets/confirm
设置新密码并撤销现有会话
以原子操作消耗密码重置令牌,存储新的 Argon2id 凭证,撤销所有已有 Session,并使其他密码重置令牌失效。不会让用户登录或创建 Session。
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"token",
"password"
],
"properties": {
"token": {
"type": "string",
"minLength": 32,
"maxLength": 256,
"writeOnly": true
},
"password": {
"$ref": "#/components/schemas/Password"
}
}
}响应
204 密码已更新;现有会话已撤销
请求头: Cache-Control, X-Request-Id
410 一次性令牌无效、已过期、已作废、已使用,或在并发确认竞争中未成功。Problem.code 为 `token_unavailable`。
请求头: Cache-Control, X-Request-Id
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 匿名身份验证请求未通过验证
请求头: Cache-Control, X-Request-Id
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 超出匿名身份验证速率限制
请求头: Cache-Control, Retry-After, X-Request-Id
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 匿名身份验证发生意外错误
请求头: Cache-Control, X-Request-Id
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 匿名身份验证依赖项暂时不可用
请求头: Cache-Control, X-Request-Id
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/auth/sessions
列出当前用户的活动会话
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 会话
请求头: Cache-Control, X-Request-Id
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Session"
}
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/auth/sessions
撤销除当前会话外的所有会话
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
204 其他会话已撤销
请求头: Cache-Control, X-Request-Id
401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/auth/sessions/{sessionId}
撤销一个会话
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
sessionId · path · 必填
结构定义
{
"type": "string",
"pattern": "^ses_"
}响应
204 会话已撤销。如果撤销的是当前 Session,Cookie 将被清除。
请求头: Set-Cookie, Cache-Control, X-Request-Id
401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/re-authenticate
为敏感操作验证当前密码
在当前服务端会话中记录短期有效的近期身份验证凭据。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"password"
],
"properties": {
"password": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"writeOnly": true
}
}
}响应
200 会话具有近期身份验证记录
请求头: Cache-Control, X-Request-Id
200 响应 · application/json
{
"$ref": "#/components/schemas/Reauthentication"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 超出请求速率、并发数、批量请求大小或待处理任务数量限制
请求头: Retry-After
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}PATCH/auth/password
更改密码并轮换当前会话
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"currentPassword",
"newPassword"
],
"properties": {
"currentPassword": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"writeOnly": true
},
"newPassword": {
"$ref": "#/components/schemas/Password"
},
"revokeOtherSessions": {
"type": "boolean",
"default": true
}
}
}响应
204 密码已更改;当前会话已轮换,并按请求撤销了其他会话
请求头: Set-Cookie, Cache-Control, X-Request-Id
401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}账户
GET/oauth/connections
列出当前账户已连接的应用
需要完整会话。账户没有已连接应用时返回空列表。响应不允许缓存。
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 已连接应用
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OAuthConnection"
}
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/oauth/connections/{grantId}
撤销已连接应用的授权及其专用 API 密钥
需要完整会话、CSRF 验证及允许的 Origin,并验证账户所有权。响应不允许缓存。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
grantId · path · 必填
结构定义
{
"type": "string",
"pattern": "^oag_[A-Za-z0-9_-]{8,}$"
}响应
204 授权已撤销
401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/account
PATCH/account
更新个人资料设置
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"$ref": "#/components/schemas/UpdateAccountRequest"
}响应
200 账户已更新
200 响应 · application/json
{
"$ref": "#/components/schemas/Account"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/account
安排删除账户,并撤销所有现有会话和 API 密钥
管理员账户必须先通过可审计的操作员流程撤销平台角色,才能安排删除。唯一的有效删除请求是天然的幂等边界。并发且经过身份验证的删除安排请求会返回同一请求。Session 撤销后,如果响应丢失,可登录 deletion_recovery 模式并读取 GET /account/deletion 进行恢复;已撤销的 Session 绝不会被接受用于重放。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"password",
"confirmation"
],
"properties": {
"password": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"writeOnly": true
},
"confirmation": {
"type": "string",
"const": "DELETE"
}
}
}响应
202 已安排删除;活动会话和密钥已撤销
202 响应 · application/json
{
"$ref": "#/components/schemas/AccountDeletionRequest"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/account/deletion
读取当前账户删除请求
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 当前删除请求
200 响应 · application/json
{
"$ref": "#/components/schemas/AccountDeletionRequest"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/account/deletion
在宽限期内取消已安排的删除
使用从 scheduled 到 cancelled 的比较并设置操作。若与处理器发生竞争,则返回 409;成功后,恢复用的 Session 会被轮换,无法重放旧的状态转换。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
204 已取消删除,账户已重新激活,并根据法律条款接受门槛轮换了恢复 Session
请求头: Set-Cookie, Cache-Control, X-Request-Id
401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/account/legal-acceptances
接受当前发布的条款和隐私政策版本
追加不可变的法律条款接受记录,清除迁移门槛,并轮换 Session。提交的过期版本会被拒绝。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"$ref": "#/components/schemas/LegalAcceptanceRequest"
}响应
200 已记录法律条款接受情况,并将 Session 轮换为完整模式
请求头: Set-Cookie, Cache-Control, X-Request-Id
200 响应 · application/json
{
"$ref": "#/components/schemas/LoginResponse"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}入门设置
GET/onboarding
读取可继续进行的入门设置进度
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 当前账户初始化状态
请求头: Cache-Control, X-Request-Id
200 响应 · application/json
{
"$ref": "#/components/schemas/OnboardingProgress"
}401 需要身份验证,或身份验证无效
请求头: Cache-Control, X-Request-Id
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 发生意外内部错误
请求头: Cache-Control, X-Request-Id
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或开户记录暂时不可用
请求头: Cache-Control, X-Request-Id
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}PATCH/onboarding
推进开户流程,且不允许进度回退
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"$ref": "#/components/schemas/UpdateOnboardingRequest"
}响应
200 新用户引导状态已更新
请求头: Cache-Control, X-Request-Id
200 响应 · application/json
{
"$ref": "#/components/schemas/OnboardingProgress"
}401 需要身份验证,或身份验证无效
请求头: Cache-Control, X-Request-Id
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
请求头: Cache-Control, X-Request-Id
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
请求头: Cache-Control, X-Request-Id
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
请求头: Cache-Control, X-Request-Id
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 发生意外内部错误
请求头: Cache-Control, X-Request-Id
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或开户记录暂时不可用
请求头: Cache-Control, X-Request-Id
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}概览
GET/overview
读取账户仪表盘汇总数据
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 账户级概览
请求头: Cache-Control, X-Request-Id
200 响应 · application/json
{
"$ref": "#/components/schemas/ConsoleOverview"
}401 需要身份验证,或身份验证无效
请求头: Cache-Control, X-Request-Id
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 发生意外内部错误
请求头: Cache-Control, X-Request-Id
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或开户记录暂时不可用
请求头: Cache-Control, X-Request-Id
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}API 密钥
GET/api-access/identity
验证当前 API Key 的所有权及定时任务就绪状态
免费读取,仅使用请求头中的 API Key。返回公开的账户和密钥 ID 及权威所有权信息,不接受请求正文,不改变现有 /api-access 元数据响应。共用每分钟 120 次的账户读取限制。不可用时应停止,不得从密钥前缀、套餐或本地状态推断所有权。不接受查询参数,响应禁止缓存。
身份验证: dataApiKey
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 验证当前 API Key 的所有权及定时任务就绪状态
200 响应 · application/json
{
"$ref": "#/components/schemas/APIKeyIdentity"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/api-keys
列出 API Key 元数据
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 不含密钥值的 API 密钥信息
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiKey"
}
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/api-keys
创建 API Key,并仅显示一次其密钥值
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
Idempotency-Key · header · 必填
结构定义
{
"type": "string",
"minLength": 1,
"maxLength": 255
}请求体 · 必填
结构定义 · application/json
{
"$ref": "#/components/schemas/CreateApiKeyRequest"
}响应
201 已创建;相同的幂等重放在五分钟内可能返回相同的加密响应
201 响应 · application/json
{
"$ref": "#/components/schemas/ApiKeyCreated"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/api-keys/{keyId}
撤销 API 密钥
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
keyId · path · 必填
结构定义
{
"type": "string",
"pattern": "^key_"
}响应
204 已撤销
401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/api-keys/{keyId}/rotate
创建替换密钥,并安排旧密钥的撤销时间
创建新密钥,并使旧密钥保持有效直到 revokeOldAt。默认重叠期为 24 小时,或截至旧密钥到期,以较早者为准。自定义 revokeOldAt 必须为未来七天内的时间,且不能晚于旧密钥到期时间。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
keyId · path · 必填
结构定义
{
"type": "string",
"pattern": "^key_"
}Idempotency-Key · header · 必填
结构定义
{
"type": "string",
"minLength": 1,
"maxLength": 255
}请求体 · 可选
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {
"revokeOldAt": {
"type": "string",
"format": "date-time",
"description": "Optional old-key revocation time; defaults to 24 hours and cannot exceed seven days or the old key expiry."
}
}
}响应
201 已创建替代密钥;密钥值仅返回一次
201 响应 · application/json
{
"$ref": "#/components/schemas/ApiKeyCreated"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/api-access
读取调用所用 API 密钥获准访问的数据源及结果来源
免费,仅通过请求头中的 X-API-Key 进行身份验证。仅返回获授权的公开数据源名称,以及配置的签名结果存储源站(不可用时为 null)。不返回账户 ID、密钥 ID、密钥值或存储凭据。本地 MCP 在每次发现工具和调用工具前都会重新验证此端点,包括读取缓存结果时。不接受查询参数或请求体。所有 /api-access 路由共用每个客户端 IP 每分钟 120 次请求的限额,并返回 Cache-Control private, no-store。仍会正常记录密钥的最近使用情况。
身份验证: dataApiKey
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 获授权的公开数据源和结果来源
200 响应 · application/json
{
"$ref": "#/components/schemas/ApiAccess"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 账户读取次数过多;请在限流窗口结束后重试
503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}智能体连接
GET/agent-connections/capabilities
查询协议 2 智能体接入是否可用
不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 查询协议 2 智能体接入是否可用
200 响应 · application/json
{
"$ref": "#/components/schemas/AgentCapabilities"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/registrations
创建或恢复临时 API Key 连接
POST 前持久保存注册凭证与确切输入。相同凭证与正文恢复同一试用,更改输入将产生冲突。临时试用为 1 Credit、72 小时、每秒 1 次请求、批大小 1。来源权限以服务器为准。不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。
身份验证: agentRegistrationProof
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"$ref": "#/components/schemas/AgentRegistrationRequest"
}响应
201 创建或恢复临时 API Key 连接
201 响应 · application/json
{
"$ref": "#/components/schemas/AgentRegistration"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/agent-connections/owned
列出浏览器账户拥有的连接
不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。此操作属于浏览器账户,需要已验证的完整会话,不能用 API Key 或凭证替代。
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 列出浏览器账户拥有的连接
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {
"connections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentConnection"
}
}
},
"required": [
"connections"
]
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/agent-connections/{connectionId}
读取临时连接状态
不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。
身份验证: agentSetupCredential
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
connectionId · path · 必填
结构定义
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}响应
200 读取临时连接状态
200 响应 · application/json
{
"$ref": "#/components/schemas/AgentConnectionResponse"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/agent-connections/{connectionId}
撤销已认领的连接
不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。此操作属于浏览器账户,需要已验证的完整会话,不能用 API Key 或凭证替代。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
connectionId · path · 必填
结构定义
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}Origin · header · 必填
结构定义
{
"type": "string"
}X-CSRF-Token · header · 必填
结构定义
{
"type": "string"
}响应
204 撤销已认领的连接
400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/agent-connections/{connectionId}/identity
验证连接当前的 Data API 密钥
不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。
身份验证: agentIdentityKey
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
connectionId · path · 必填
结构定义
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}响应
200 验证连接当前的 Data API 密钥
200 响应 · application/json
{
"$ref": "#/components/schemas/AgentConnectionResponse"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/agent-connections/{connectionId}/onboarding
读取可恢复的接入状态
不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。
身份验证: agentHandoffProof
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
connectionId · path · 必填
结构定义
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}响应
200 读取可恢复的接入状态
200 响应 · application/json
{
"$ref": "#/components/schemas/AgentOnboardingStatus"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/{connectionId}/claims
创建浏览器授权认领
在可信的 FlashData 网站来源打开 claimPath,并单独展示确认码。切勿将凭据或确认码放入 URL。不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。
身份验证: agentSetupCredential
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
connectionId · path · 必填
结构定义
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {},
"required": []
}响应
201 创建浏览器授权认领
201 响应 · application/json
{
"$ref": "#/components/schemas/AgentClaim"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/claims/{claimId}/confirm
在已验证的浏览器会话中核对认领确认码
不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。此操作属于浏览器账户,需要已验证的完整会话,不能用 API Key 或凭证替代。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
claimId · path · 必填
结构定义
{
"type": "string",
"pattern": "^acl_[A-Za-z0-9_-]{8,100}$"
}Origin · header · 必填
结构定义
{
"type": "string"
}X-CSRF-Token · header · 必填
结构定义
{
"type": "string"
}请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"pattern": "^\\d{8}$"
}
},
"required": [
"code"
]
}响应
200 在已验证的浏览器会话中核对认领确认码
200 响应 · application/json
{
"$ref": "#/components/schemas/AgentBrowserClaim"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/agent-connections/claims/{claimId}
在对应浏览器会话中读取已确认的认领
不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。此操作属于浏览器账户,需要已验证的完整会话,不能用 API Key 或凭证替代。
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
claimId · path · 必填
结构定义
{
"type": "string",
"pattern": "^acl_[A-Za-z0-9_-]{8,100}$"
}响应
200 在对应浏览器会话中读取已确认的认领
200 响应 · application/json
{
"$ref": "#/components/schemas/AgentClaimView"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/claims/{claimId}/approve
批准缩减后的权限及账户余额使用
不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。此操作属于浏览器账户,需要已验证的完整会话,不能用 API Key 或凭证替代。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
claimId · path · 必填
结构定义
{
"type": "string",
"pattern": "^acl_[A-Za-z0-9_-]{8,100}$"
}Origin · header · 必填
结构定义
{
"type": "string"
}X-CSRF-Token · header · 必填
结构定义
{
"type": "string"
}请求体 · 必填
结构定义 · application/json
{
"$ref": "#/components/schemas/AgentApproval"
}响应
200 批准缩减后的权限及账户余额使用
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {
"connection": {
"$ref": "#/components/schemas/AgentConnection"
},
"handoff": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"status",
"expiresAt"
]
}
},
"required": [
"connection",
"handoff"
]
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/{connectionId}/handoff
恢复已获批准的所有者 API Key
候选密钥在安装确认前有效期为 24 小时。原子保存后,从新进程重新读取并验证身份,再确认安装。重复交付返回同一候选密钥;已确认的交付仅返回回执,不含凭据。不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。
身份验证: agentHandoffProof
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
connectionId · path · 必填
结构定义
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {},
"required": []
}响应
200 恢复已获批准的所有者 API Key
200 响应 · application/json
{
"$ref": "#/components/schemas/AgentHandoff"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/{connectionId}/handoff/ack
确认已验证的所有者密钥安装
调用前必须已保存候选密钥,并从新进程独立验证。成功确认后标记为已安装,移除候选密钥有效期,并删除可恢复的凭据材料。重复确认具有幂等性。不接受查询参数,响应禁止缓存。智能体路由仅由管理服务提供并受功能开关控制;关闭时可能返回 404。智能体路由禁止使用 X-API-Key。
身份验证: agentHandoffProof
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
connectionId · path · 必填
结构定义
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {
"apiKey": {
"type": "string"
}
},
"required": [
"apiKey"
]
}响应
200 确认已验证的所有者密钥安装
200 响应 · application/json
{
"$ref": "#/components/schemas/AgentHandoff"
}400 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
400 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
429 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 请求被拒绝,请检查 Problem 错误码。切勿盲目重试修改操作。
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}目录
GET/catalog/sources
列出公开数据源能力,不包含账户专属价格
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 公开数据源目录
请求头: Cache-Control
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DataSource"
}
}
}
}GET/plans
列出公开的美元套餐与价格
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 公开套餐目录
请求头: Cache-Control
200 响应 · application/json
{
"$ref": "#/components/schemas/PlanCatalog"
}GET/legal/current
读取注册所需的当前服务条款和隐私政策版本
身份验证: 公开访问
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 当前法律文件版本目录
请求头: Cache-Control
200 响应 · application/json
{
"$ref": "#/components/schemas/PublicLegalVersions"
}计费
GET/billing/subscription
读取当前生效的 Stripe 订阅
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 订阅或按量付费权益
200 响应 · application/json
{
"$ref": "#/components/schemas/Subscription"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/billing/checkout-sessions
创建由 Stripe 托管的 Checkout Session
订阅和已公布的积分包使用 priceId。自定义充值则使用 amountMinor(美元分,金额范围为 $10 至 $999,999.99);服务器按固定积分价值计算积分,并创建私有的一次性 Stripe 价格。浏览器不得传入产品、服务商价格、币种、成功 URL 或取消 URL。只有在与报价金额一致的已付款事件通过验证后,才会发放积分。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
Idempotency-Key · header · 必填
结构定义
{
"type": "string",
"minLength": 1,
"maxLength": 255
}请求体 · 必填
结构定义 · application/json
{
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"priceId"
],
"properties": {
"priceId": {
"type": "string",
"pattern": "^prc_"
},
"purchaseType": {
"type": "string",
"enum": [
"subscription",
"top_up"
],
"default": "subscription"
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"amountMinor",
"purchaseType"
],
"properties": {
"amountMinor": {
"type": "integer",
"minimum": 1000,
"maximum": 99999999,
"description": "Custom top-up amount in USD cents."
},
"purchaseType": {
"type": "string",
"const": "top_up"
}
}
}
]
}响应
201 Stripe Checkout Session
201 响应 · application/json
{
"$ref": "#/components/schemas/HostedSession"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}502 上游服务商发生故障
502 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 计费目录或支付服务商尚未配置,或暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/billing/subscription-changes
将当前 Stripe 订阅升级到已发布的更高价格
服务器会验证 FlashData 价格是否处于启用状态、在当前 livemode 下可用、以 USD 计价、采用周期性计费、计费周期相同,且严格高于当前订阅价格。浏览器传入的产品、支付服务商价格、币种及按比例计费选项一律不予接受。只有在已验证的支付服务商事件被应用到本地状态后,本地权益和积分才会变更。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
Idempotency-Key · header · 必填
结构定义
{
"type": "string",
"minLength": 1,
"maxLength": 255
}请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"priceId"
],
"properties": {
"priceId": {
"type": "string",
"pattern": "^prc_"
}
}
}响应
201 订阅变更已提交至 Stripe
201 响应 · application/json
{
"$ref": "#/components/schemas/SubscriptionChange"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}502 上游服务商发生故障
502 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 计费目录或支付服务商尚未配置,或暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/billing/portal-sessions
创建 Stripe Customer Portal Session
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
Idempotency-Key · header · 必填
结构定义
{
"type": "string",
"minLength": 1,
"maxLength": 255
}响应
201 Stripe Customer Portal Session
201 响应 · application/json
{
"$ref": "#/components/schemas/HostedSession"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}502 上游服务商发生故障
502 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 计费目录或支付服务商尚未配置,或暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/billing/subscription-cancellation
安排取消当前付费订阅,或撤销取消安排
将 cancelAtPeriodEnd 设为 true 会安排在当前计费周期结束时取消订阅;设为 false 则保留订阅。权益会在 Stripe 订阅事件通过验证后更新。此端点不会立即取消订阅,也不会退款。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
Idempotency-Key · header · 必填
结构定义
{
"type": "string",
"minLength": 1,
"maxLength": 255
}请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"cancelAtPeriodEnd"
],
"properties": {
"cancelAtPeriodEnd": {
"type": "boolean"
}
}
}响应
202 取消更新已提交到 Stripe
202 响应 · application/json
SubscriptionCancellationChange
{
"$ref": "#/components/schemas/SubscriptionCancellationChange"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}502 上游服务商发生故障
502 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 计费目录或支付服务商尚未配置,或暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/billing/invoices
列出 Stripe 发票投影数据
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
cursor · query · 可选
结构定义
{
"type": "string",
"maxLength": 512
}limit · query · 可选
结构定义
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}响应
200 发票
401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/billing/payments
列出账户范围内的充值与退款支付投影数据
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
cursor · query · 可选
结构定义
{
"type": "string",
"maxLength": 512
}limit · query · 可选
结构定义
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}响应
200 一次性付款记录,不含支付服务商密钥
200 响应 · application/json
{
"$ref": "#/components/schemas/BillingPaymentPage"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}积分
GET/api-access/balance
使用 API 密钥读取账户实时余额
读取账户内所有 API Key 共用的当前 Credits 余额。正在进行的额度预留可能减少可用余额。此请求不消耗 Credits,无需查询参数或请求体。响应为私有且不缓存,并受账户读取速率限制。
身份验证: dataApiKey
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 可为负数的余额和非负的可用积分
200 响应 · application/json
{
"$ref": "#/components/schemas/ApiAccessBalance"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 账户读取次数过多;请在限流窗口结束后重试
503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/api-access/pricing
读取 API 密钥获准访问的数据源的实际账户价格
读取 API Key 允许访问的接口所对应的账户费率。价格为 null 表示该接口不可用。request_count 统计查询次数而非返回条数;下载费率按 TB(10^12 字节)计算。估算不会预留 Credits 或容量。此请求不消耗 Credits,响应为私有且不缓存,并受账户读取速率限制。
身份验证: dataApiKey
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
source · query · 可选
此密钥获授权的数据源;省略时读取所有获授权的数据源。
结构定义
{
"$ref": "#/components/schemas/ApiAccessSource"
}request_count · query · 可选
十进制整数形式的调用次数;不估算下载大小。
结构定义
{
"type": "integer",
"minimum": 1,
"maximum": 100000,
"default": 1
}响应
200 账户套餐和各数据源价格
200 响应 · application/json
{
"$ref": "#/components/schemas/ApiAccessPricing"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 账户读取次数过多;请在限流窗口结束后重试
503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/api-access/limits
使用 API 密钥读取账户套餐限制和当前待处理任务
读取并发、批量大小、待处理任务上限及当前待处理数量。这些值可用于规划请求,但不会预留容量。此请求不消耗 Credits,无需查询参数或请求体。响应为私有且不缓存,并受账户读取速率限制。
身份验证: dataApiKey
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 套餐上限和当前待处理数量
200 响应 · application/json
{
"$ref": "#/components/schemas/ApiAccessLimits"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 账户读取次数过多;请在限流窗口结束后重试
503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/usage
读取 API 密钥获准访问的数据源的账户用量
免费读取,仅通过 X-API-Key 进行身份验证。包含账户所有密钥的数据,但仅限调用密钥获授权的数据源。不返回查询文本、密钥、支付详情或其他账户的数据。默认查询七天,最长 31 天。日期必须使用 UTC Z 时间戳。From 包含起始时间,to 不包含结束时间;两者均向下取整到分钟。仅提供 from 时,to 默认为 from + 7 days。两者均未提供时,to 为下一分钟的起始时间。汇总数据具有最终一致性;即使 updating=false,也不保证所有近期事件都已写入。读取限额:每个客户端 IP 每分钟 60 次请求。
身份验证: dataApiKey
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
source · query · 可选
调用密钥获授权的确切目录数据源;省略时表示所有获授权的数据源。
结构定义
{
"type": "string",
"enum": [
"google_search",
"google_images",
"google_news",
"google_shopping",
"google_videos",
"google_places",
"youtube_search",
"youtube_search_extended",
"youtube_metadata",
"youtube_transcript",
"youtube_captions",
"youtube_trainability",
"youtube_channel",
"youtube_suggestions",
"youtube_download"
]
}from · query · 可选
结构定义
{
"type": "string",
"format": "date-time"
}to · query · 可选
结构定义
{
"type": "string",
"format": "date-time"
}响应
200 指定范围内的请求数量和已扣除积分,附带数据时效信息
200 响应 · application/json
{
"$ref": "#/components/schemas/ApiKeyUsage"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 用量读取次数过多;请在限流窗口结束后重试
503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/credits/balance
读取当前可用积分和预留积分
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 积分余额
200 响应 · application/json
{
"$ref": "#/components/schemas/CreditBalance"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/credits/policy
读取当前生效的账户积分发放及扣费政策
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 生效的积分策略
200 响应 · application/json
{
"$ref": "#/components/schemas/CreditPolicy"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/credits/transactions
列出积分账本记录
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
cursor · query · 可选
结构定义
{
"type": "string",
"maxLength": 512
}limit · query · 可选
结构定义
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}type · query · 可选
结构定义
{
"$ref": "#/components/schemas/CreditEntryType"
}响应
200 账本记录
200 响应 · application/json
{
"allOf": [
{
"$ref": "#/components/schemas/Page"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreditTransaction"
}
}
}
}
]
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}试用积分
GET/trial-credit-request
读取试用积分资格及账户唯一一次的申请记录
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 当前资格、配置的赠送额度及申请状态
请求头: Cache-Control
200 响应 · application/json
{
"$ref": "#/components/schemas/TrialCreditState"
}401 需要身份验证,或身份验证无效
请求头: Cache-Control, X-Request-Id
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 发生意外内部错误
请求头: Cache-Control, X-Request-Id
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或开户记录暂时不可用
请求头: Cache-Control, X-Request-Id
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/trial-credit-request
提交账户唯一一次的试用积分申请
提交请求时会保存试用额度及使用场景。
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
Idempotency-Key · header · 必填
结构定义
{
"type": "string",
"minLength": 1,
"maxLength": 255
}请求体 · 可选
结构定义 · application/json
{
"type": "object",
"additionalProperties": false
}响应
201 试用额度申请已创建;所有邮箱服务商的符合条件且已验证账户均自动获批。
请求头: Cache-Control
201 响应 · application/json
{
"$ref": "#/components/schemas/TrialCreditState"
}401 需要身份验证,或身份验证无效
请求头: Cache-Control, X-Request-Id
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 已通过身份验证但无权限,或 CSRF 验证失败
请求头: Cache-Control, X-Request-Id
403 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
请求头: Cache-Control, X-Request-Id
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
请求头: Cache-Control, X-Request-Id
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 发生意外内部错误
请求头: Cache-Control, X-Request-Id
500 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或开户记录暂时不可用
请求头: Cache-Control, X-Request-Id
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}交付
GET/delivery/webhooks
列出已保存的完成回调 URL
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
响应
200 回调 URL
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DeliveryWebhook"
}
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/delivery/webhooks
保存完成回调 URL
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"$ref": "#/components/schemas/CreateDeliveryWebhookRequest"
}响应
201 已创建
201 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"webhook"
],
"properties": {
"webhook": {
"$ref": "#/components/schemas/DeliveryWebhook"
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/delivery/webhooks/{webhookId}
移除完成回调 URL
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
webhookId · path · 必填
结构定义
{
"type": "string",
"pattern": "^cbk_[A-Za-z0-9_-]{8,}$"
}响应
204 已移除
401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/delivery/webhooks/{webhookId}/test
发送下载完成的示例载荷
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
webhookId · path · 必填
结构定义
{
"type": "string",
"pattern": "^cbk_[A-Za-z0-9_-]{8,}$"
}响应
200 已尝试测试
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"statusCode",
"webhook"
],
"properties": {
"statusCode": {
"type": "integer",
"minimum": 0
},
"webhook": {
"$ref": "#/components/schemas/DeliveryWebhook"
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}任务
GET/jobs
列出当前工作区的 Data API 任务
使用游标分页查询活动和归档历史记录。默认查询最近七天;每个 UTC 日期范围最多为 31 天。From 包含起始时间,to 不包含结束时间,精确到分钟。摘要以异步方式维护,可能滞后于数据写入。
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
cursor · query · 可选
结构定义
{
"type": "string",
"minLength": 1,
"maxLength": 512
}limit · query · 可选
结构定义
{
"type": "integer",
"minimum": 1,
"maximum": 50
}source · query · 可选
结构定义
{
"type": "string",
"pattern": "^(google|youtube|google_[a-z]+|youtube_[a-z_]+)$"
}status · query · 可选
结构定义
{
"type": "string",
"enum": [
"completed",
"failed",
"pending",
"processing"
]
}mode · query · 可选
结构定义
{
"type": "string",
"enum": [
"async",
"batch",
"realtime"
]
}from · query · 可选
结构定义
{
"type": "string",
"format": "date-time"
}to · query · 可选
结构定义
{
"type": "string",
"format": "date-time"
}响应
200 任务页面
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination",
"summary"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConsoleJob"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
},
"summary": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"completed",
"credits",
"failed",
"total"
],
"properties": {
"completed": {
"type": "integer",
"minimum": 0
},
"credits": {
"type": "number",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
},
"updating": {
"type": "boolean"
}
}
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/jobs/{jobId}
读取一个 Data API 任务
通过 job.status 查看进度,处理失败时通过 job.error 查看原因。默认返回 JSON;可用 Accept: text/plain 获取可读文本。此接口忽略 X-Respond-With。再次查询前,请按 Retry-After 提示等待。
身份验证: cookieSession 或 dataApiKey
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
Accept · header · 可选
application/json 返回原有结构化响应;text/plain 使用缩进纯文本展示相同字段。支持标准媒体范围和 q 权重;省略 Accept 或使用 */* 时默认返回 JSON。提交和任务状态接口忽略 X-Respond-With。错误保持结构化 JSON。 两种响应均使用 UTF-8,支持显式 charset=utf-8 参数。
结构定义
{
"type": "string"
}jobId · path · 必填
结构定义
{
"type": "string",
"pattern": "^job_[A-Za-z0-9_-]+$"
}响应
200 任务详情
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"job"
],
"properties": {
"job": {
"$ref": "#/components/schemas/ConsoleJob"
}
}
}200 响应 · text/plain
{
"type": "string"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}406 客户端不接受 application/json 或 text/plain;返回 JSON 错误
406 响应 · application/json
{
"$ref": "#/components/schemas/QueryRepresentationError"
}GET/jobs/{jobId}/results
下载已完成的异步结果
默认验证访问权限并跳转到短期有效的私有 R2 URL,由 R2 直接返回原始 JSON。Accept: text/plain 可独立选择缩进纯文本,直接以 HTTP 200 返回原始结果字段。X-Respond-With: markdown 选择 Markdown 内容:application/json 用 content 承载正文,替换 results,并保留原始元数据;text/plain 返回元数据和 Markdown。省略 Accept 或使用全局通配符时默认返回 JSON。格式化不会再次提交查询或收取查询 Credits。结果在完成 24 小时后过期,错误保持结构化 JSON。
身份验证: cookieSession 或 dataApiKey
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
X-Respond-With · header · 可选
设置为 markdown 可将结果内容转为 Markdown;省略时保留原始字段。Accept 独立选择 JSON 或纯文本。此请求头仅用于实时查询及已完成结果读取,不用于提交回执、任务状态、账户接口、回调、Bulk 文件、媒体文件或 MCP 响应。
结构定义
{
"type": "string",
"enum": [
"markdown"
]
}Accept · header · 可选
通过 Accept 独立选择 application/json 或 text/plain。省略 X-Respond-With 时保留原始字段;默认 JSON 的完成结果读取会跳转到存储。选择 markdown 时,JSON 返回 content 及元数据,纯文本返回元数据及 Markdown。支持媒体范围和 q 权重;省略 Accept 或使用通配符时默认返回 JSON。两种响应均使用 UTF-8,并支持 charset=utf-8。
结构定义
{
"type": "string"
}jobId · path · 必填
结构定义
{
"type": "string",
"pattern": "^job_[A-Za-z0-9_-]+$"
}响应
200 直接返回原始字段的纯文本或 Markdown;原始 JSON 在跟随默认跳转后由 R2 返回
200 响应 · application/json
{
"anyOf": [
{
"$ref": "#/components/schemas/MarkdownQueryResult"
},
{
"type": "object",
"additionalProperties": true
}
]
}200 响应 · text/plain
{
"type": "string"
}302 未指定 X-Respond-With 且选择 JSON 时,跳转到私有 R2 存储中的原始 JSON
请求头: Location
400 不支持的 X-Respond-With 值;返回 JSON 错误
400 响应 · application/json
{
"$ref": "#/components/schemas/QueryRepresentationError"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}406 客户端不接受 application/json 或 text/plain;返回 JSON 错误
406 响应 · application/json
{
"$ref": "#/components/schemas/QueryRepresentationError"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 结果已过期
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 任务失败。若已保存失败原因,响应会在 detail 字段中返回该原因。
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Bulk 处理 API
Bulk 端点的参数、请求示例和响应结构位于独立参考页面。 打开 Bulk 处理 API
GET /v2/bulk-jobs· 列出 YouTube 文件批处理任务POST /v2/bulk-jobs· 创建 Bulk 任务并获取文件上传 URLGET /v2/bulk-jobs/{bulkId}· 读取文件批处理任务进度及汇总计数PATCH /v2/bulk-jobs/{bulkId}· 修改尚未开始处理的视频设置DELETE /v2/bulk-jobs/{bulkId}· 取消 Bulk 任务POST /v2/bulk-jobs/{bulkId}/start· 开始扫描已上传的 YouTube ID 文件POST /v2/bulk-jobs/{bulkId}/pause· 暂停 Bulk 任务POST /v2/bulk-jobs/{bulkId}/resume· 恢复手动或自动暂停的文件批处理任务GET /v2/bulk-jobs/{bulkId}/results· 下载已完成的文件批处理清单GET /v2/bulk-jobs/{bulkId}/results/{partNumber}· 下载一个 gzip 压缩的 NDJSON 文件批处理结果分片
调试台
POST/playground/run
以当前工作区的身份运行调试台查询
身份验证: cookieSession + csrfToken
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
请求体 · 必填
结构定义 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"source",
"mode",
"query"
],
"properties": {
"source": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"realtime",
"async",
"batch"
]
},
"query": {
"description": "Source request body. In batch mode, also accepts an object containing only queries, an array of 1 to 20 request bodies. Every entry must match the selected source and its input schema. Search and Suggestions require query; Channel requires handle; Metadata, Transcript, Captions, Trainability and Download require an 11-character video_id matching [A-Za-z0-9_-]. Download batch entries must supply params.storage for customer storage; console browser delivery is not supported in this envelope. Account batch and pending-job limits still apply.",
"type": "object",
"additionalProperties": true
}
}
}响应
200 为交互体验区采集的上游 Data API 响应
200 响应 · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"body",
"endpoint",
"mode",
"status"
],
"properties": {
"body": {},
"endpoint": {
"type": "string",
"enum": [
"/v1/queries",
"/v1/queries/batch",
"/v1/queries/realtime"
]
},
"mode": {
"type": "string",
"enum": [
"realtime",
"async",
"batch"
]
},
"status": {
"type": "integer",
"minimum": 100,
"maximum": 599
}
}
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 请求校验失败
422 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/playground/jobs/{jobId}/download
在当前浏览器中下载已完成的 Playground 产物
身份验证: cookieSession
服务器: https://api.flashdata.dev/v2
服务器: http://localhost:5000/v2
参数
jobId · path · 必填
结构定义
{
"type": "string",
"pattern": "^job_[A-Za-z0-9_-]+$"
}响应
200 用于浏览器下载的临时文件
请求头: Content-Disposition, Content-Length
200 响应 · application/octet-stream
{
"type": "string",
"format": "binary"
}401 需要身份验证,或身份验证无效
401 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 未找到资源,或资源不属于调用者
404 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 资源状态或幂等性冲突
409 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 临时产物已过期
410 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 必需的依赖项或目录暂时不可用
503 响应 · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Schema 定义
APIKeyIdentity
{
"type": "object",
"additionalProperties": false,
"properties": {
"apiKeyId": {
"type": "string"
},
"accountId": {
"type": "string"
},
"accountType": {
"type": "string",
"enum": [
"owned",
"temporary"
]
},
"ownership": {
"type": "string",
"enum": [
"owned",
"unowned"
]
},
"access": {
"type": "string",
"enum": [
"ready",
"blocked"
]
},
"installed": {
"type": "boolean"
},
"recurringAllowed": {
"type": "boolean"
},
"connectionId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"expiresAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"verifiedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"apiKeyId",
"accountId",
"accountType",
"ownership",
"access",
"installed",
"recurringAllowed",
"connectionId",
"scopes",
"expiresAt",
"verifiedAt"
],
"description": "Authoritative current-record ownership and readiness. Public IDs only. recurringAllowed requires a verified active owner and, for agent-issued keys, server-confirmed installation. It is a point-in-time check, not an authorization token or permission to reuse cached data after revocation."
}Account
{
"type": "object",
"description": "Deleted accounts are only returned through authorized Admin projections; their identity fields are redacted.",
"additionalProperties": false,
"required": [
"id",
"name",
"email",
"status",
"emailVerified",
"legalAcceptanceRequired",
"role",
"timezone",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^acct_"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
],
"format": "email"
},
"status": {
"type": "string",
"enum": [
"pending_verification",
"active",
"suspended",
"deleting",
"deleted"
]
},
"emailVerified": {
"type": "boolean"
},
"legalAcceptanceRequired": {
"type": "boolean"
},
"role": {
"type": "string",
"enum": [
"user",
"admin"
]
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}AccountDeletionRequest
{
"type": "object",
"description": "User-safe deletion summary. Durable processor cursor and per-step metadata are internal operational state and are intentionally omitted.",
"additionalProperties": false,
"required": [
"id",
"status",
"requestedAt",
"scheduledFor",
"cancellable",
"billingCancellationStatus",
"activeJobsAtRequest",
"retryable"
],
"properties": {
"id": {
"type": "string",
"pattern": "^del_"
},
"status": {
"type": "string",
"enum": [
"scheduled",
"cancelled",
"processing",
"completed",
"failed"
]
},
"requestedAt": {
"type": "string",
"format": "date-time"
},
"scheduledFor": {
"type": "string",
"format": "date-time"
},
"cancellable": {
"type": "boolean"
},
"cancelledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"processingStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureCode": {
"type": [
"string",
"null"
],
"maxLength": 80
},
"billingCancellationStatus": {
"type": "string",
"enum": [
"not_required",
"pending",
"completed",
"failed"
]
},
"activeJobsAtRequest": {
"type": "integer",
"minimum": 0
},
"retryable": {
"type": "boolean",
"description": "True only when an Admin-audited processor retry is possible; it does not grant the user mutation access."
}
}
}AgentApproval
{
"type": "object",
"additionalProperties": false,
"properties": {
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"allowAccountBalance": {
"const": true
}
},
"required": [
"scopes",
"allowAccountBalance"
]
}AgentBrowserClaim
{
"type": "object",
"additionalProperties": false,
"properties": {
"connection": {
"$ref": "#/components/schemas/AgentConnection"
},
"claimId": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"connection",
"claimId",
"expiresAt"
]
}AgentCapabilities
{
"type": "object",
"additionalProperties": false,
"properties": {
"protocolVersion": {
"const": 2
},
"available": {
"type": "boolean"
},
"flow": {
"const": "temporary_account_api_key"
},
"dataOrigin": {
"type": "string"
},
"queryPath": {
"const": "/v1/queries/realtime"
},
"credentialType": {
"const": "api_key"
},
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentPermission"
}
},
"owner": {
"type": "object",
"additionalProperties": false,
"required": [
"scopes"
],
"properties": {
"scopes": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"trial": {
"type": "object",
"additionalProperties": false,
"properties": {
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"credits": {
"type": "number"
},
"lifetimeHours": {
"type": "integer",
"minimum": 0
},
"requestsPerSecond": {
"type": "integer",
"minimum": 0
},
"maxBatchSize": {
"type": "integer",
"minimum": 0
},
"requestCounts": {}
},
"required": [
"credits",
"lifetimeHours",
"requestsPerSecond",
"maxBatchSize",
"requestCounts"
]
},
"recurringRequires": {
"const": "owned_key_installed"
},
"replayProtection": {
"const": "client_local_only"
}
},
"required": [
"protocolVersion",
"available"
]
}AgentClaim
{
"type": "object",
"additionalProperties": false,
"properties": {
"claimId": {
"type": "string"
},
"claimPath": {
"type": "string"
},
"confirmationCode": {
"type": "string",
"pattern": "^\\d{8}$"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"pollAfterSeconds": {
"type": "integer",
"minimum": 0
}
},
"required": [
"claimId",
"claimPath",
"confirmationCode",
"expiresAt",
"pollAfterSeconds"
]
}AgentClaimView
{
"type": "object",
"additionalProperties": false,
"required": [
"connection"
],
"properties": {
"connection": {
"$ref": "#/components/schemas/AgentConnection"
},
"handoff": {
"type": "object",
"additionalProperties": false,
"required": [
"status"
],
"properties": {
"status": {
"type": "string"
}
}
}
}
}AgentConnection
{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"audience": {
"type": "string",
"enum": [
"coding",
"personal",
"unspecified"
]
},
"ownership": {
"type": "string",
"enum": [
"owned",
"unowned"
]
},
"lifecycle": {
"type": "string",
"enum": [
"valid",
"revoked",
"expired"
]
},
"access": {
"type": "string",
"enum": [
"ready",
"fenced",
"blocked"
]
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actual scopes on the current API key. May be empty on an unowned claim-only connection; every data-source request is then forbidden."
},
"requestedScopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Original owner-access request. Claim approval can only reduce this set. Legacy connections retain their original scopes."
},
"trialScopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Saved subset eligible for the temporary key. Never expanded by catalog changes."
},
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentPermission"
}
},
"generation": {
"type": "integer",
"minimum": 0
},
"installed": {
"type": "boolean"
},
"trialExpiresAt": {
"type": "string",
"format": "date-time"
},
"fundingMode": {
"type": "string",
"enum": [
"trial",
"account_balance"
]
},
"trialCredits": {
"type": "number"
},
"trialRequestCounts": {}
},
"required": [
"id",
"name",
"audience",
"ownership",
"lifecycle",
"access",
"scopes",
"generation",
"installed",
"trialExpiresAt",
"fundingMode",
"trialCredits",
"trialRequestCounts"
]
}AgentConnectionResponse
{
"type": "object",
"additionalProperties": false,
"properties": {
"connection": {
"$ref": "#/components/schemas/AgentConnection"
}
},
"required": [
"connection"
]
}AgentHandoff
{
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"enum": [
"delivered",
"confirmed"
]
},
"connection": {
"$ref": "#/components/schemas/AgentConnection"
},
"credentials": {
"$ref": "#/components/schemas/AgentCredentials"
},
"generation": {
"type": "integer",
"minimum": 0
}
},
"required": [
"status"
]
}AgentCredentials
{
"type": "object",
"additionalProperties": false,
"properties": {
"connectionId": {
"type": "string"
},
"apiKey": {
"type": "string"
},
"setupCredential": {
"type": "string"
},
"handoffProof": {
"type": "string"
},
"generation": {
"type": "integer",
"minimum": 0
}
},
"required": [
"connectionId",
"apiKey",
"generation"
],
"description": "Sensitive ordinary API-key credentials. Never log or put in browser URLs. Proofs are returned on temporary registration; handoff returns the owned candidate key."
}AgentOnboardingStatus
{
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"enum": [
"awaiting_claim",
"claim_processing",
"handoff_ready",
"installed",
"handoff_expired",
"expired",
"revoked",
"blocked"
]
},
"connection": {
"$ref": "#/components/schemas/AgentConnection"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"nextAction": {
"type": "string"
},
"pollAfterSeconds": {
"type": "integer",
"minimum": 0
}
},
"required": [
"status"
]
}AgentPermission
{
"type": "object",
"additionalProperties": false,
"required": [
"source",
"name",
"product",
"trialEligible",
"ownerAllowed",
"requiresStorageDestination"
],
"properties": {
"source": {
"type": "string",
"pattern": "^[a-z_]{1,80}$"
},
"name": {
"type": "string"
},
"product": {
"type": "string"
},
"trialEligible": {
"type": "boolean"
},
"ownerAllowed": {
"type": "boolean"
},
"requiresStorageDestination": {
"type": "boolean"
}
},
"description": "Catalog-derived agent permissions. Trial eligibility is an explicit opt-in independent of owner approval. Storage and variable-price sources require owner access."
}AgentRegistration
{
"type": "object",
"additionalProperties": false,
"properties": {
"connection": {
"$ref": "#/components/schemas/AgentConnection"
},
"credentials": {
"$ref": "#/components/schemas/AgentCredentials"
},
"dataOrigin": {
"type": "string"
},
"deniedScopes": {
"type": "array",
"items": {
"type": "string"
}
},
"limits": {
"type": "object",
"additionalProperties": true
},
"nextAction": {
"type": "string",
"enum": [
"query_or_claim",
"claim"
],
"description": "Claim before the first data request when no requested source is trial eligible."
}
},
"required": [
"connection",
"credentials",
"dataOrigin",
"deniedScopes",
"limits"
]
}AgentRegistrationRequest
{
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"audience": {
"type": "string",
"enum": [
"coding",
"personal"
]
},
"scopes": {
"type": "array",
"minItems": 1,
"maxItems": 30,
"uniqueItems": true,
"items": {
"type": "string",
"pattern": "^[a-z_]{1,80}$"
}
},
"client": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
},
"transport": {
"type": "string",
"enum": [
"api",
"cli",
"mcp"
]
}
},
"required": [
"name",
"scopes"
]
}ApiAccess
{
"type": "object",
"additionalProperties": false,
"required": [
"sources",
"result_origin"
],
"properties": {
"sources": {
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/ApiAccessSource"
}
},
"result_origin": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Configured signed-result storage origin, without credentials, path, query or fragment. Not an access token or a media URL."
}
}
}ApiAccessBalance
{
"type": "object",
"additionalProperties": false,
"required": [
"scope",
"unit",
"balanceCredits",
"availableCredits",
"updatedAt",
"note"
],
"properties": {
"scope": {
"type": "string",
"const": "account"
},
"unit": {
"type": "string",
"const": "Credits"
},
"balanceCredits": {
"type": "number",
"description": "Signed live balance; in-flight reservations may already be reflected."
},
"availableCredits": {
"type": "number",
"minimum": 0,
"description": "max(balanceCredits, 0)."
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"note": {
"type": "string"
}
}
}ApiAccessLimits
{
"type": "object",
"additionalProperties": false,
"required": [
"scope",
"plan",
"limits",
"current",
"note"
],
"properties": {
"scope": {
"type": "string",
"const": "account"
},
"plan": {
"$ref": "#/components/schemas/ApiAccessPlan"
},
"limits": {
"type": "object",
"additionalProperties": false,
"properties": {
"concurrency": {
"type": "integer",
"minimum": 0
},
"batchSize": {
"type": "integer",
"minimum": 0
},
"pendingJobs": {
"type": "integer",
"minimum": 0
}
}
},
"current": {
"type": "object",
"additionalProperties": false,
"required": [
"pendingJobs"
],
"properties": {
"pendingJobs": {
"type": "integer",
"minimum": 0
}
}
},
"note": {
"type": "string"
}
}
}ApiAccessPlan
{
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"billingMode": {
"type": "string"
},
"status": {
"type": "string"
}
}
}ApiAccessPricing
{
"type": "object",
"additionalProperties": false,
"required": [
"unit",
"plan",
"requestCount",
"prices",
"note"
],
"properties": {
"unit": {
"type": "string",
"const": "Credits"
},
"plan": {
"$ref": "#/components/schemas/ApiAccessPlan"
},
"requestCount": {
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"prices": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"source",
"available",
"estimatedCredits"
],
"properties": {
"source": {
"$ref": "#/components/schemas/ApiAccessSource"
},
"available": {
"type": "boolean"
},
"creditsPerRequest": {
"type": [
"number",
"null"
],
"minimum": 0
},
"estimatedCredits": {
"type": [
"number",
"null"
],
"minimum": 0,
"description": "Null for downloads or missing pricing."
},
"billingUnit": {
"type": "string",
"const": "TB"
},
"bytesPerUnit": {
"type": "integer",
"const": 1000000000000
},
"creditsPerTb": {
"type": [
"number",
"null"
],
"minimum": 0
},
"note": {
"type": "string"
}
}
}
},
"note": {
"type": "string"
}
}
}ApiAccessSource
{
"type": "string",
"enum": [
"google_search",
"google_images",
"google_news",
"google_shopping",
"google_videos",
"google_places",
"youtube_search",
"youtube_search_extended",
"youtube_metadata",
"youtube_transcript",
"youtube_captions",
"youtube_trainability",
"youtube_channel",
"youtube_suggestions",
"youtube_download"
]
}ApiKey
{
"type": "object",
"description": "API key details. A key remains active until scheduledRevocationAt when revocation is scheduled.",
"additionalProperties": false,
"required": [
"id",
"name",
"prefix",
"last4",
"scopes",
"status",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^key_"
},
"name": {
"type": "string"
},
"prefix": {
"type": "string"
},
"last4": {
"type": "string",
"minLength": 4,
"maxLength": 4
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"active",
"revoked",
"expired"
]
},
"lastUsedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledRevocationAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Planned revocation time for an overlapping retiring key; null for a primary or immediately revoked key."
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}ApiKeyCreated
{
"type": "object",
"additionalProperties": false,
"required": [
"apiKey",
"secret"
],
"properties": {
"apiKey": {
"$ref": "#/components/schemas/ApiKey"
},
"secret": {
"type": "string",
"readOnly": true,
"pattern": "^fd_(?:(?:test|live)_)?[A-Za-z0-9_-]{43}$",
"description": "Plaintext secret returned only by this create/rotate transaction. Newly issued secrets use the `fd_` prefix. Previously issued `fd_test_` and `fd_live_` secrets still authenticate. An authenticated replay with the same Idempotency-Key and request body may receive the same KMS-encrypted response for five minutes; it is not recoverable afterward.",
"x-secret-reveal": "once"
}
}
}ApiKeyUsage
{
"type": "object",
"additionalProperties": false,
"required": [
"scope",
"unit",
"from",
"to",
"observedAt",
"totals",
"bySource",
"updating",
"note"
],
"properties": {
"scope": {
"type": "string",
"const": "account_authorized_sources"
},
"unit": {
"type": "string",
"const": "Credits"
},
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
},
"observedAt": {
"type": "string",
"format": "date-time"
},
"totals": {
"$ref": "#/components/schemas/UsageCounts"
},
"bySource": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"source",
"requests",
"completed",
"failed",
"credits"
],
"properties": {
"source": {
"type": "string"
},
"requests": {
"type": "integer",
"minimum": 0
},
"completed": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"credits": {
"type": "number",
"minimum": 0
}
}
}
},
"updating": {
"type": "boolean"
},
"note": {
"type": "string"
}
}
}BillingPaymentPage
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BillingPayment"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
}BillingPayment
{
"description": "Account-scoped top-up projection. Refund state is updated only from verified provider events; this API does not initiate refunds.",
"type": "object",
"additionalProperties": false,
"required": [
"id",
"purchaseType",
"status",
"currency",
"amount",
"refundedAmount",
"credits",
"reversedCredits",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^pay_"
},
"purchaseType": {
"type": "string",
"const": "top_up"
},
"status": {
"type": "string",
"enum": [
"pending",
"paid",
"partially_refunded",
"refunded",
"failed"
]
},
"currency": {
"type": "string",
"const": "USD"
},
"amount": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"refundedAmount": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"credits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001
},
"hostedInvoiceUrl": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Stripe-hosted HTTPS invoice URL, when Stripe created an invoice for this top-up."
},
"invoiceNumber": {
"type": [
"string",
"null"
],
"description": "Stripe invoice number, when available."
},
"reversedCredits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001,
"description": "Cumulative credits removed by append-only payment_reversal entries; never exceeds credits."
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}BulkJobCreated
{
"type": "object",
"additionalProperties": false,
"required": [
"job",
"upload"
],
"properties": {
"job": {
"$ref": "#/components/schemas/BulkJob"
},
"upload": {
"type": "object",
"additionalProperties": false,
"required": [
"href",
"method",
"expiresAt",
"contentType"
],
"properties": {
"href": {
"type": "string",
"format": "uri"
},
"method": {
"type": "string",
"const": "PUT"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"contentType": {
"type": "string",
"const": "text/plain; charset=utf-8"
}
}
}
}
}BulkJob
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"source",
"status",
"input",
"counts",
"delivery",
"pauseReason",
"error",
"createdAt",
"startedAt",
"completedAt",
"expiresAt",
"links"
],
"properties": {
"id": {
"type": "string",
"pattern": "^bulk_[A-Za-z0-9_-]{8,}$"
},
"source": {
"type": "string",
"enum": [
"youtube_metadata",
"youtube_transcript",
"youtube_captions",
"youtube_trainability",
"youtube_download"
]
},
"status": {
"type": "string",
"enum": [
"awaiting_upload",
"running",
"paused",
"finalizing",
"completed",
"failed",
"cancelled"
]
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"bytes",
"complete",
"scannedBytes",
"scannedLines"
],
"properties": {
"bytes": {
"type": "integer",
"minimum": 0
},
"complete": {
"type": "boolean"
},
"scannedBytes": {
"type": "integer",
"minimum": 0
},
"scannedLines": {
"type": "integer",
"minimum": 0
}
}
},
"counts": {
"type": "object",
"additionalProperties": false,
"required": [
"accepted",
"completed",
"failed",
"invalid",
"results"
],
"properties": {
"accepted": {
"type": "integer",
"minimum": 0
},
"completed": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"invalid": {
"type": "integer",
"minimum": 0
},
"results": {
"type": "integer",
"minimum": 0
}
}
},
"pauseReason": {
"type": [
"string",
"null"
]
},
"delivery": {
"type": "object",
"additionalProperties": false,
"required": [
"customerStorage",
"storageType",
"uploadedParts",
"retryCount"
],
"properties": {
"customerStorage": {
"type": "boolean"
},
"storageType": {
"type": [
"string",
"null"
],
"enum": [
"s3",
"s3_compatible",
"oss",
"gcs",
"azure",
"cos",
"bos",
"tos",
null
]
},
"uploadedParts": {
"type": "integer",
"minimum": 0
},
"retryCount": {
"type": "integer",
"minimum": 0
}
}
},
"error": {
"oneOf": [
{
"type": "null"
},
{
"type": "object",
"additionalProperties": false,
"required": [
"code",
"detail"
],
"properties": {
"code": {
"type": "string"
},
"detail": {
"type": [
"string",
"null"
]
}
}
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"startedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"links": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobLink"
}
}
}
}BulkJobPage
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BulkJob"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
}BulkJobResponse
{
"type": "object",
"additionalProperties": false,
"required": [
"job"
],
"properties": {
"job": {
"$ref": "#/components/schemas/BulkJob"
}
}
}ConsoleJob
{
"type": "object",
"additionalProperties": false,
"required": [
"createdAt",
"credits",
"durationMs",
"error",
"id",
"params",
"progress",
"result",
"source",
"status",
"updatedAt",
"videoId"
],
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"credits": {
"type": "number",
"multipleOf": 0.001
},
"durationMs": {
"type": [
"number",
"null"
],
"minimum": 0
},
"error": {
"type": [
"string",
"null"
]
},
"id": {
"type": "string"
},
"params": {
"type": "object",
"additionalProperties": true
},
"progress": {
"type": "integer",
"minimum": 0
},
"result": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"source": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"completed",
"failed",
"pending",
"processing"
]
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"videoId": {
"type": [
"string",
"null"
]
},
"links": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobLink"
}
}
}
}ConsoleOverview
{
"type": "object",
"additionalProperties": false,
"required": [
"account",
"onboarding",
"subscription",
"balance",
"publicStatus",
"degradedSections",
"generatedAt"
],
"properties": {
"account": {
"$ref": "#/components/schemas/Account"
},
"onboarding": {
"$ref": "#/components/schemas/OnboardingProgress"
},
"subscription": {
"oneOf": [
{
"$ref": "#/components/schemas/Subscription"
},
{
"type": "null"
}
]
},
"balance": {
"oneOf": [
{
"$ref": "#/components/schemas/CreditBalance"
},
{
"type": "null"
}
]
},
"publicStatus": {
"oneOf": [
{
"$ref": "#/components/schemas/PublicStatus"
},
{
"type": "null"
}
]
},
"degradedSections": {
"type": "array",
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"subscription",
"balance",
"public_status"
]
},
"description": "A listed section uses its unavailable representation; null and empty values must not be interpreted as zero or healthy."
},
"generatedAt": {
"type": "string",
"format": "date-time"
}
}
}CreateApiKeyRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"scopes"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"scopes": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"google_search",
"google_images",
"google_news",
"google_shopping",
"google_videos",
"google_places",
"youtube_search",
"youtube_search_extended",
"youtube_metadata",
"youtube_transcript",
"youtube_captions",
"youtube_trainability",
"youtube_channel",
"youtube_suggestions",
"youtube_download"
]
}
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}CreateBulkJobRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"source"
],
"properties": {
"source": {
"type": "string",
"enum": [
"youtube_metadata",
"youtube_transcript",
"youtube_captions",
"youtube_trainability",
"youtube_download"
]
},
"options": {
"type": "object",
"additionalProperties": true,
"description": "Reused for every ID. Metadata accepts include_formats and include_chapters. Transcript and captions accept language (one code or an array of 1–10 distinct codes) and auto (applies to all requested languages). Omit language to prefer en-orig, fall back to en, and return one track. With auto=true, each requested code tries its -orig track first, then the plain code. Explicit -orig codes and auto=false stay exact. languageCode identifies the selected track; requestedLanguageCode is included when it differs from the requested code. A language array returns tracks and per-language errors for each video with at least one retrieved track. If no track is retrieved, the video job fails and its reserved credits are refunded. Bulk exports use one JSONL record per video. Trainability accepts no source options. These four data sources optionally accept result_storage. Supported storage_type values are s3, s3_compatible, oss, gcs, azure, cos, bos, and tos. storage_url is the bucket name (Azure container name); object_prefix is optional. S3, S3-compatible, OSS, COS, BOS, and TOS use access_key and secret_key. S3-compatible and OSS also require a public HTTPS endpoint_url. COS, BOS, and TOS require region and use fixed provider endpoints. COS bucket names include the APPID. BOS S3-compatible HTTPS delivery supports bj, su, and hkg. GCS requires service_account with project_id, client_email, and private_key. Azure requires account_name and a container SAS sas_token with write permission. Default object_prefix is YYYYMMDD, frozen to the UTC bulk creation date. Files are written to <prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz; manifest.json in the same bulk directory is written last. Each JSONL row includes its input index and completed, failed, or invalid status. Internal R2 results remain available through the result links for 24 hours. Download accepts the normal YouTube download parameters, requires customer storage, and does not permit browser_delivery. Download storage supports the same eight provider types and credential shapes listed above under the storage field. Download storage may include object_prefix; YYYYMMDD tokens resolve to the UTC upload date, while literal prefixes are unchanged."
},
"callback_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Optional public HTTPS endpoint notified once after manifest publication."
}
}
}CreateDeliveryWebhookRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
}
}
}CreditBalance
{
"type": "object",
"additionalProperties": false,
"required": [
"balanceCredits",
"reservedCredits",
"availableCredits",
"lifetimeGrantedCredits",
"lifetimeUsedCredits",
"lifetimeRefundedCredits",
"lifetimePaymentReversedCredits",
"updatedAt"
],
"properties": {
"balanceCredits": {
"type": "number",
"multipleOf": 0.001,
"description": "Signed settled balance after grants, usage, refunds and provider reversals."
},
"reservedCredits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001
},
"availableCredits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001,
"description": "max(balanceCredits, 0)."
},
"lifetimeGrantedCredits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001
},
"lifetimeUsedCredits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001
},
"lifetimeRefundedCredits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001,
"description": "Credits returned to the account after failed usage."
},
"lifetimePaymentReversedCredits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001,
"description": "Absolute Credits removed after verified provider refunds or chargebacks."
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}CreditEntryType
{
"type": "string",
"enum": [
"subscription_grant",
"topup_grant",
"payment_reversal",
"admin_adjustment",
"trial_grant"
]
}CreditPolicy
{
"type": "object",
"additionalProperties": false,
"required": [
"unit",
"failedRequestsCharged",
"subscriptionGrantTiming",
"refundHandling"
],
"properties": {
"unit": {
"type": "string",
"const": "credit"
},
"failedRequestsCharged": {
"type": "boolean",
"const": false
},
"subscriptionGrantTiming": {
"type": "string",
"const": "invoice_paid"
},
"refundHandling": {
"type": "string",
"const": "append_only_reversal",
"description": "Failed requests are refunded; verified provider refunds remove the proportional Credits through immutable transactions."
}
}
}CreditTransaction
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type",
"deltaCredits",
"balanceAfterCredits",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^ctx_"
},
"type": {
"$ref": "#/components/schemas/CreditEntryType"
},
"deltaCredits": {
"type": "number",
"multipleOf": 0.001
},
"balanceAfterCredits": {
"type": [
"number",
"null"
],
"multipleOf": 0.001,
"description": "Signed settled balance after this immutable transaction, when recorded."
},
"description": {
"type": "string"
},
"requestId": {
"type": [
"string",
"null"
]
},
"jobId": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}DataSource
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"category",
"product",
"modes",
"inputSchema",
"estimatedCredits",
"requiresStorageDestination"
],
"properties": {
"id": {
"type": "string",
"enum": [
"google_search",
"google_images",
"google_news",
"google_shopping",
"google_videos",
"google_places",
"youtube_search",
"youtube_search_extended",
"youtube_metadata",
"youtube_transcript",
"youtube_captions",
"youtube_trainability",
"youtube_channel",
"youtube_suggestions",
"youtube_download"
]
},
"name": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"google",
"youtube"
]
},
"product": {
"type": "string",
"enum": [
"google_search",
"youtube_data",
"youtube_download"
]
},
"modes": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"description": "Only modes backed by a real adapter or consumer in the current release",
"items": {
"type": "string",
"enum": [
"realtime",
"async",
"batch"
]
}
},
"inputSchema": {
"type": "object",
"additionalProperties": true,
"description": "JSON Schema used by the Playground and generated clients"
},
"estimatedCredits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001
},
"requiresStorageDestination": {
"type": "boolean",
"description": "Whether query submission must include per-request storage configuration."
}
}
}DeliveryWebhook
{
"type": "object",
"additionalProperties": false,
"required": [
"createdAt",
"id",
"lastTestStatus",
"lastTestedAt",
"name",
"status",
"updatedAt",
"url"
],
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"id": {
"type": "string",
"pattern": "^cbk_[A-Za-z0-9_-]{8,}$"
},
"lastTestStatus": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"lastTestedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"active",
"disabled"
]
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"url": {
"type": "string",
"format": "uri"
}
}
}Health
{
"type": "object",
"additionalProperties": false,
"required": [
"status",
"service",
"version",
"time"
],
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"degraded"
]
},
"service": {
"type": "string"
},
"version": {
"type": "string"
},
"time": {
"type": "string",
"format": "date-time"
}
}
}HostedSession
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"url",
"expiresAt"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri",
"description": "Provider-hosted HTTPS URL on a Stripe-controlled *.stripe.com host. Web clients must validate the origin and redirect from a server-only boundary."
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}Invoice
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"number",
"status",
"currency",
"total",
"amountPaid",
"refundedAmount",
"billingReason",
"createdAt",
"periodStart",
"periodEnd"
],
"properties": {
"id": {
"type": "string",
"pattern": "^inv_"
},
"number": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft",
"open",
"paid",
"void",
"uncollectible"
]
},
"currency": {
"type": "string",
"const": "USD"
},
"total": {
"type": "integer",
"description": "USD cents"
},
"amountPaid": {
"type": "integer",
"description": "USD cents"
},
"refundedAmount": {
"type": "integer",
"minimum": 0,
"description": "Cumulative USD cents observed from verified provider events."
},
"billingReason": {
"type": [
"string",
"null"
],
"enum": [
"subscription_create",
"subscription_cycle",
"subscription_update",
null
]
},
"hostedInvoiceUrl": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Stripe-hosted HTTPS invoice URL. Production Web clients accept only Stripe-controlled *.stripe.com origins."
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"periodStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"periodEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}JobLink
{
"type": "object",
"additionalProperties": false,
"required": [
"rel",
"href",
"method"
],
"properties": {
"rel": {
"type": "string",
"enum": [
"self",
"results",
"content",
"download"
]
},
"href": {
"type": "string",
"format": "uri"
},
"method": {
"type": "string",
"const": "GET"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"filename": {
"type": "string"
},
"content_type": {
"type": "string"
},
"size_bytes": {
"type": "integer",
"minimum": 1
}
}
}LegalAcceptanceRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"acceptedTerms",
"termsVersion",
"privacyVersion"
],
"properties": {
"acceptedTerms": {
"type": "boolean",
"const": true
},
"termsVersion": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"privacyVersion": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
}
}LoginRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 320
},
"password": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"writeOnly": true
},
"rememberMe": {
"type": "boolean",
"default": false,
"description": "Ignored for email_verification, legal_acceptance and deletion_recovery Sessions, which always use a short fixed expiry."
}
}
}LoginResponse
{
"type": "object",
"additionalProperties": false,
"required": [
"account",
"csrfToken",
"sessionMode"
],
"properties": {
"account": {
"$ref": "#/components/schemas/Account"
},
"csrfToken": {
"type": "string",
"minLength": 32,
"readOnly": true
},
"sessionMode": {
"type": "string",
"enum": [
"full",
"email_verification",
"legal_acceptance",
"deletion_recovery"
]
}
}
}MarkdownQueryResult
{
"type": "object",
"required": [
"source",
"status",
"content"
],
"additionalProperties": true,
"description": "Markdown result content. content replaces the results array; other response fields such as id, source, status, usage and timestamps are preserved. No generated summary is added. Source URLs and transcript segment start/end times are retained.",
"properties": {
"source": {
"type": "string"
},
"status": {
"type": "string"
},
"content": {
"type": "string",
"description": "Deterministic Markdown derived from the retrieved source result."
},
"usage": {
"type": "object",
"additionalProperties": true
}
}
}OAuthConnection
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"clientName",
"scope",
"status",
"createdAt",
"expiresAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^oag_[A-Za-z0-9_-]{8,}$"
},
"clientName": {
"type": "string"
},
"scope": {
"type": "string",
"enum": [
"mcp:research"
]
},
"status": {
"type": "string",
"enum": [
"active",
"expired",
"revoked"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}OAuthConsent
{
"type": "object",
"additionalProperties": false,
"required": [
"clientName",
"scope",
"sources",
"redirectUri",
"expiresAt"
],
"properties": {
"clientName": {
"type": "string",
"maxLength": 80
},
"scope": {
"type": "string",
"enum": [
"mcp:research"
]
},
"sources": {
"type": "array",
"items": {
"type": "string",
"enum": [
"google_search",
"youtube_search",
"youtube_metadata",
"youtube_transcript"
]
}
},
"redirectUri": {
"type": "string",
"format": "uri"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}OnboardingProgress
{
"type": "object",
"additionalProperties": false,
"required": [
"currentStep",
"apiKeyStepStatus",
"firstRequestStatus",
"version",
"updatedAt"
],
"properties": {
"currentStep": {
"type": "string",
"enum": [
"welcome",
"api_key",
"first_request",
"completed"
]
},
"useCase": {
"type": [
"string",
"null"
],
"enum": [
"google_search",
"youtube_data",
"download",
null
]
},
"apiKeyStepStatus": {
"type": "string",
"enum": [
"pending",
"created",
"skipped"
]
},
"firstRequestStatus": {
"type": "string",
"enum": [
"pending",
"succeeded",
"skipped"
]
},
"firstApiKeyId": {
"type": [
"string",
"null"
],
"pattern": "^key_"
},
"firstRequestId": {
"type": [
"string",
"null"
],
"pattern": "^req_"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"version": {
"type": "integer",
"minimum": 0
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}Page
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination"
],
"properties": {
"data": {
"type": "array",
"items": {}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
}Pagination
{
"type": "object",
"additionalProperties": false,
"required": [
"hasMore",
"limit"
],
"properties": {
"nextCursor": {
"type": [
"string",
"null"
]
},
"previousCursor": {
"type": [
"string",
"null"
]
},
"hasMore": {
"type": "boolean"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
}
}Password
{
"type": "string",
"minLength": 8,
"maxLength": 128,
"writeOnly": true
}PlanCatalog
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"currency",
"billingAvailability",
"creditValueUsd"
],
"properties": {
"trialOffer": {
"description": "Current one-time trial allowance expressed as alternative PAYG usage amounts. Eligibility and approval are required. The amounts share one balance and are not additive. Null when a reliable estimate is unavailable. This is not an account eligibility decision or a promise of immediate credit issuance.",
"oneOf": [
{
"$ref": "#/components/schemas/PublicTrialOffer"
},
{
"type": "null"
}
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Plan"
}
},
"currency": {
"type": "string",
"const": "USD"
},
"creditValueUsd": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Fixed USD value of one credit, used to preview custom top-ups. The server computes the credited amount."
},
"billingAvailability": {
"type": "string",
"enum": [
"available",
"unconfigured",
"unavailable"
]
},
"billingMessage": {
"type": [
"string",
"null"
],
"description": "Stable, non-sensitive explanation suitable for the Pricing and Billing UI."
}
}
}Plan
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"slug",
"name",
"description",
"includedCredits",
"limits",
"prices",
"features",
"usagePrices"
],
"properties": {
"id": {
"type": "string",
"pattern": "^plan_"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"includedCredits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001,
"description": "Credits included in each paid subscription cycle; zero for Pay As You Go."
},
"limits": {
"$ref": "#/components/schemas/PlanLimits"
},
"prices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlanPrice"
}
},
"features": {
"type": "array",
"items": {
"type": "string"
}
},
"usagePrices": {
"$ref": "#/components/schemas/PlanUsagePrices"
}
}
}PlanLimits
{
"type": "object",
"additionalProperties": false,
"required": [
"concurrency",
"maxBatchSize",
"maxPendingJobs"
],
"properties": {
"concurrency": {
"type": "integer",
"minimum": 1
},
"maxBatchSize": {
"type": "integer",
"minimum": 1
},
"maxPendingJobs": {
"type": "integer",
"minimum": 1
}
}
}PlanPrice
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"currency",
"unitAmount",
"credits",
"type",
"interval"
],
"properties": {
"id": {
"type": "string",
"pattern": "^prc_"
},
"currency": {
"type": "string",
"const": "USD"
},
"unitAmount": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"credits": {
"type": "number",
"minimum": 0,
"multipleOf": 0.001,
"description": "Credits granted by a successful one-time top-up; zero for recurring prices."
},
"type": {
"type": "string",
"enum": [
"recurring",
"one_time"
]
},
"interval": {
"type": [
"string",
"null"
],
"enum": [
"month",
"year",
null
]
}
}
}PlanUsagePrices
{
"type": "object",
"additionalProperties": false,
"required": [
"googlePer1kCents",
"youtubePer1kCents",
"downloadPerTbCents"
],
"properties": {
"googlePer1kCents": {
"type": "integer",
"minimum": 0,
"description": "Google request price per 1,000 successful requests, in USD cents."
},
"youtubePer1kCents": {
"type": "integer",
"minimum": 0,
"description": "Standard YouTube request price per 1,000 successful requests, in USD cents."
},
"downloadPerTbCents": {
"type": "integer",
"minimum": 0,
"description": "Download price per decimal TB (1,000,000,000,000 bytes), in USD cents."
}
}
}Problem
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code",
"requestId"
],
"properties": {
"type": {
"type": "string",
"format": "uri-reference"
},
"title": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"pattern": "^[a-z0-9_]+$"
},
"detail": {
"type": "string"
},
"requestId": {
"type": "string",
"pattern": "^req_"
},
"fieldErrors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldError"
}
}
}
}FieldError
{
"type": "object",
"additionalProperties": false,
"required": [
"field",
"code",
"message"
],
"properties": {
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}PublicLegalVersions
{
"type": "object",
"additionalProperties": false,
"required": [
"availability",
"termsVersion",
"privacyVersion"
],
"properties": {
"availability": {
"type": "string",
"enum": [
"configured",
"unconfigured"
]
},
"termsVersion": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 64
},
"privacyVersion": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 64
}
}
}PublicStatus
{
"type": "object",
"additionalProperties": false,
"required": [
"status",
"updatedAt",
"components"
],
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"degraded",
"outage"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"components": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicStatusComponent"
}
}
}
}PublicStatusComponent
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"status"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"operational",
"degraded",
"outage"
]
}
}
}PublicTrialOffer
{
"type": "object",
"additionalProperties": false,
"required": [
"googleSearchRequests",
"youtubeDataRequests",
"downloadGigabytes"
],
"properties": {
"maxApiRequests": {
"type": "integer",
"minimum": 0,
"description": "Maximum free API calls when the entire trial grant is spent on the lowest-cost per-request API at current Pay as you go rates. Other APIs may allow fewer calls. Downloads are billed by delivered bytes and excluded from this count."
},
"googleSearchRequests": {
"type": "integer",
"minimum": 0,
"description": "Requests if the entire grant is spent on Google sources, using the highest current source rate."
},
"youtubeDataRequests": {
"type": "integer",
"minimum": 0,
"description": "Standard YouTube requests, excluding Extended Search, using the highest current source rate."
},
"downloadGigabytes": {
"type": "number",
"minimum": 0,
"description": "Approximate delivered media volume in decimal GB (1 GB = 1000000000 bytes). Zero when the grant cannot cover the initial download reservation. Completion also depends on per-job reservations and settlement."
}
}
}QueryRepresentationError
{
"type": "object",
"required": [
"error",
"code",
"message"
],
"properties": {
"error": {
"type": "boolean",
"const": true
},
"code": {
"type": "string",
"enum": [
"unsupported_representation",
"not_acceptable"
]
},
"message": {
"type": "string"
}
}
}Reauthentication
{
"type": "object",
"additionalProperties": false,
"required": [
"reauthenticatedUntil"
],
"properties": {
"reauthenticatedUntil": {
"type": "string",
"format": "date-time"
}
}
}RegisterRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"email",
"password",
"acceptedTerms",
"termsVersion",
"privacyVersion"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional display name. When omitted, defaults to the normalized email local part, truncated to 100 characters. Can be changed in the profile later."
},
"email": {
"type": "string",
"format": "email",
"maxLength": 320
},
"password": {
"$ref": "#/components/schemas/Password"
},
"acceptedTerms": {
"type": "boolean",
"const": true
},
"termsVersion": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Exact version rendered by the signup page; stale versions are rejected."
},
"privacyVersion": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Exact version rendered by the signup page; stale versions are rejected."
}
}
}RegisterResponse
{
"type": "object",
"additionalProperties": false,
"description": "Generic receipt returned for both a new account and a recoverable pending account. It intentionally omits identity data to limit account enumeration.",
"required": [
"emailVerificationRequired"
],
"properties": {
"emailVerificationRequired": {
"type": "boolean",
"const": true
}
}
}Session
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"current",
"mode",
"createdAt",
"lastSeenAt",
"expiresAt",
"device"
],
"properties": {
"id": {
"type": "string",
"pattern": "^ses_"
},
"current": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"full",
"email_verification",
"legal_acceptance",
"deletion_recovery"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"lastSeenAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"device": {
"type": "string"
},
"approximateLocation": {
"type": "string"
},
"reauthenticatedUntil": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}Subscription
{
"type": "object",
"description": "Effective entitlement projection. `status=payg` and `id=null` means no billing subscription record exists.",
"additionalProperties": false,
"required": [
"status",
"plan",
"cancelAtPeriodEnd",
"usageRates"
],
"properties": {
"id": {
"type": [
"string",
"null"
],
"pattern": "^sub_"
},
"status": {
"type": "string",
"enum": [
"payg",
"trialing",
"active",
"past_due",
"grace",
"cancelled"
]
},
"plan": {
"$ref": "#/components/schemas/Plan"
},
"usageRates": {
"type": "object",
"description": "Account-specific configured credit rates. Query rates come from the account entitlement, not the public plan catalog. One TB is 1,000,000,000,000 bytes; download charges are settled against actual bytes and rounded per result.",
"additionalProperties": false,
"required": [
"customized",
"queries",
"downloadCreditsPerTb"
],
"properties": {
"customized": {
"type": "boolean",
"description": "True when an administrator configured rates for this account."
},
"queries": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"source",
"name",
"creditsPerRequest"
],
"properties": {
"source": {
"type": "string"
},
"name": {
"type": "string"
},
"creditsPerRequest": {
"type": "number",
"minimum": 0
}
}
}
},
"downloadCreditsPerTb": {
"type": "number",
"minimum": 0
}
}
},
"currentPeriodStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"currentPeriodEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelAtPeriodEnd": {
"type": "boolean"
},
"graceEndsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}SubscriptionCancellationChange
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"cancelAtPeriodEnd",
"status"
],
"properties": {
"id": {
"type": "string",
"pattern": "^sub_"
},
"cancelAtPeriodEnd": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": [
"submitted"
]
}
}
}SubscriptionChange
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"fromPriceId",
"toPriceId",
"effective",
"status"
],
"properties": {
"id": {
"type": "string",
"pattern": "^sub_",
"description": "FlashData subscription public ID. Entitlement still updates only after a verified provider event."
},
"fromPriceId": {
"type": "string",
"pattern": "^prc_"
},
"toPriceId": {
"type": "string",
"pattern": "^prc_"
},
"effective": {
"type": "string",
"enum": [
"immediate"
]
},
"status": {
"type": "string",
"enum": [
"submitted"
]
}
}
}TokenRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"token"
],
"properties": {
"token": {
"type": "string",
"minLength": 32,
"maxLength": 256,
"writeOnly": true
}
}
}TrialCreditState
{
"type": "object",
"additionalProperties": false,
"required": [
"eligible",
"ineligibilityReason",
"grantCredits",
"settingsVersion",
"request"
],
"properties": {
"eligible": {
"type": "boolean"
},
"ineligibilityReason": {
"type": [
"string",
"null"
],
"enum": [
"account_inactive",
"email_unverified",
"onboarding_incomplete",
"not_payg",
"payment_history",
"already_granted",
"already_requested",
null
]
},
"grantCredits": {
"type": "integer",
"minimum": 1
},
"settingsVersion": {
"type": "integer",
"minimum": 0
},
"request": {
"oneOf": [
{
"$ref": "#/components/schemas/TrialCreditRequest"
},
{
"type": "null"
}
]
}
}
}TrialCreditRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"status",
"requestedCredits",
"policyVersion",
"useCase",
"requestedAt",
"reviewedAt",
"reviewReason",
"version"
],
"properties": {
"id": {
"type": "string",
"pattern": "^tcr_[A-Za-z0-9_-]{8,}$"
},
"status": {
"$ref": "#/components/schemas/TrialCreditRequestStatus"
},
"requestedCredits": {
"type": "integer",
"minimum": 1
},
"policyVersion": {
"type": "integer",
"minimum": 0
},
"useCase": {
"type": [
"string",
"null"
],
"enum": [
"google_search",
"youtube_data",
"download",
null
]
},
"requestedAt": {
"type": "string",
"format": "date-time"
},
"reviewedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"reviewReason": {
"type": [
"string",
"null"
]
},
"version": {
"type": "integer",
"minimum": 0
}
}
}TrialCreditRequestStatus
{
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
}UpdateAccountRequest
{
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
}
}UpdateBulkJobRequest
{
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"properties": {
"options": {
"type": "object",
"additionalProperties": true,
"description": "Partial option update. Nested storage fields are merged so unchanged credentials do not need to be resent. Data result_storage fields are merged the same way. After all IDs have been scanned, a paused data bulk job accepts credential updates only: access_key and secret_key, GCS service_account, or Azure sas_token, depending on the storage type. The complete merged configuration is validated before it is stored."
},
"callback_url": {
"type": [
"string",
"null"
],
"format": "uri",
"maxLength": 2048,
"description": "Replacement completion callback, or null to remove the callback."
}
}
}UpdateOnboardingRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"version",
"action"
],
"properties": {
"version": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"action": {
"type": "string",
"enum": [
"select_use_case",
"confirm_api_key_saved",
"skip_api_key",
"confirm_first_request",
"skip_first_request"
]
},
"useCase": {
"type": "string",
"enum": [
"google_search",
"youtube_data",
"download"
]
}
},
"allOf": [
{
"if": {
"properties": {
"action": {
"const": "select_use_case"
}
}
},
"then": {
"required": [
"useCase"
],
"properties": {
"useCase": {}
}
},
"else": {
"not": {
"required": [
"useCase"
],
"properties": {
"useCase": {}
}
}
}
}
],
"description": "Server-owned resource state validates confirmation actions; clients never submit API Key or request IDs."
}UsageCounts
{
"type": "object",
"additionalProperties": false,
"required": [
"requests",
"completed",
"failed",
"credits"
],
"properties": {
"requests": {
"type": "integer",
"minimum": 0
},
"completed": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"credits": {
"type": "number",
"minimum": 0,
"description": "Charged Credits in the current aggregate; pending work may not be finally settled."
}
}
}