Browse documentation
API reference
Management API reference
Browse endpoints for accounts, keys, billing and jobs. Each endpoint lists its own authentication and access requirements.
Read your account with an API key
The Management API base URL is https://api.flashdata.dev/v2. This free read returns the current key and account IDs and ownership. Set FLASHDATA_API_KEY before running the command.
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'Expect HTTP 200 on success. Check each endpoint's Authentication line: dataApiKey uses X-API-Key; cookieSession uses a signed-in browser session. Identity response schema
Download the customer OpenAPI specification. It covers queries, jobs, accounts, API keys and billing.
Query parameters and request code are documented in the Google and YouTube API references.
Authentication schemes
| Scheme | Requirement |
|---|---|
dataApiKey |
FlashData API key. Job access is restricted to the key's source scopes. |
cookieSession |
Opaque Web session. The browser cannot read this cookie. |
csrfToken |
apiKey |
agentRegistrationProof | Persist a cryptographically random 32-byte base64url proof and exact request BEFORE sending; recover only with the same proof and body. Not an OAuth token. |
agentSetupCredential | Temporary setup credential for status and claim creation only. Not a data API key. |
agentHandoffProof | Proof used to recover the owner key and acknowledge installation. Never sent to a data query. |
agentIdentityKey | Ordinary FlashData API key in Authorization Bearer, only on agent identity. Data queries use X-API-Key instead. |
System
GET/health
Service health
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Healthy
200 response · application/json
{
"$ref": "#/components/schemas/Health"
}GET/status
Read the public component status summary
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Public status summary
Headers: Cache-Control
200 response · application/json
{
"$ref": "#/components/schemas/PublicStatus"
}Auth
GET/oauth/requests/{requestId}
Read an app authorization request and bind it to the current session
Full session required. Request expires after ten minutes. Response is no-store.
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
requestId · path · required
Schema
{
"type": "string",
"pattern": "^fdo_[A-Za-z0-9_-]{43}$"
}Responses
200 Requested app permissions
200 response · application/json
{
"$ref": "#/components/schemas/OAuthConsent"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Request expired, used, or bound to another session
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/oauth/requests/{requestId}
Approve or deny an app authorization request
Full session, CSRF and allowed Origin required. Consumes the request once. Response is no-store.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
requestId · path · required
Schema
{
"type": "string",
"pattern": "^fdo_[A-Za-z0-9_-]{43}$"
}Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"decision"
],
"properties": {
"decision": {
"type": "string",
"enum": [
"approve",
"deny"
]
}
}
}Responses
200 Registered client callback with code or denial, state and issuer
200 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"redirectUrl"
],
"properties": {
"redirectUrl": {
"type": "string",
"format": "uri"
}
}
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Authorization request unavailable; start a new connection
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/register
Create a pending FlashData account
The submitted Terms and Privacy versions must match the current published legal bundle.
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"$ref": "#/components/schemas/RegisterRequest"
}Responses
201 Account created; email verification required
Headers: Cache-Control, X-Request-Id
201 response · application/json
{
"$ref": "#/components/schemas/RegisterResponse"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rate, concurrency, batch, or pending-job limit exceeded
Headers: Retry-After
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected internal error occurred
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/login
Create an opaque Web session
Sets the Secure, HttpOnly `__Host-fd_session` cookie. Pending accounts receive a restricted email_verification Session for the verification dashboard. Eligible verified accounts receive their one-time Trial Credits on login if not already granted. An active account receives a full Session unless its migrated identity still requires a current legal acceptance, in which case it receives a restricted legal_acceptance Session. An account with a scheduled deletion request receives a restricted deletion_recovery Session. Accounts whose deletion is processing/failed/completed, and suspended accounts, receive 403.
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"$ref": "#/components/schemas/LoginRequest"
}Responses
200 Authenticated
Headers: Set-Cookie, Cache-Control, X-Request-Id
200 response · application/json
{
"$ref": "#/components/schemas/LoginResponse"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Login is forbidden; Problem.code is email_not_verified, account_suspended, account_deletion_processing, account_deletion_failed, or account_deleted
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}423 Account temporarily locked
Headers: Retry-After
423 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rate, concurrency, batch, or pending-job limit exceeded
Headers: Retry-After
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/logout
Revoke the current session
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
204 Session revoked and cookie cleared
Headers: Set-Cookie, Cache-Control, X-Request-Id
401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/auth/me
Read the current account and user
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Current account
Headers: Cache-Control, X-Request-Id
200 response · application/json
{
"$ref": "#/components/schemas/Account"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/auth/csrf
Get the CSRF token bound to the current session
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 CSRF token
Headers: Cache-Control, X-Request-Id
200 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"csrfToken"
],
"properties": {
"csrfToken": {
"type": "string",
"minLength": 32,
"readOnly": true
}
}
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/email-verifications
Request or resend an email verification message
For every syntactically valid email, returns the same response regardless of whether the account is missing, pending, active, suspended, or deleted. Eligible pending accounts receive a rotated one-time link after the resend cooldown.
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 320
}
}
}Responses
202 Request accepted. The response does not reveal whether an account exists.
Headers: Cache-Control, X-Request-Id
202 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"accepted"
],
"properties": {
"accepted": {
"type": "boolean",
"const": true
}
}
}422 Anonymous authentication request validation failed
Headers: Cache-Control, X-Request-Id
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Anonymous authentication rate limit exceeded
Headers: Cache-Control, Retry-After, X-Request-Id
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected anonymous authentication error occurred
Headers: Cache-Control, X-Request-Id
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 An anonymous authentication dependency is temporarily unavailable
Headers: Cache-Control, X-Request-Id
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/email-verifications/confirm
Verify an email and activate the account
Atomically consumes the one-time token and activates the Account and User. Existing account and trial-credit rules apply. Without a signup Session the user logs in explicitly. An allowed-origin request carrying the matching signup Session and its X-CSRF-Token may receive a rotated Session cookie for the same verified account; a verification token alone never signs in a user.
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"$ref": "#/components/schemas/TokenRequest"
}Responses
200 Account activated
Headers: Set-Cookie, Cache-Control, X-Request-Id
200 response · application/json
{
"allOf": [
{
"$ref": "#/components/schemas/Account"
},
{
"type": "object",
"properties": {
"status": {
"const": "active"
},
"emailVerified": {
"const": true
}
}
}
]
}410 One-time token is invalid, expired, invalidated, already used, or lost a concurrent confirmation race. Problem.code is `token_unavailable`.
Headers: Cache-Control, X-Request-Id
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Anonymous authentication request validation failed
Headers: Cache-Control, X-Request-Id
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Anonymous authentication rate limit exceeded
Headers: Cache-Control, Retry-After, X-Request-Id
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected anonymous authentication error occurred
Headers: Cache-Control, X-Request-Id
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 An anonymous authentication dependency is temporarily unavailable
Headers: Cache-Control, X-Request-Id
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/email-verifications/session
Continue the original signup session after email verification
Requires an allowed Origin and the CSRF token bound to a live password-authenticated email-verification Session. Returns pending until that Session's own account is verified, including verification in another browser. Atomically revokes the signup Session and issues a fresh full or legal-acceptance Session. Does not accept an account ID, email, password or verification token, bypass legal acceptance, or grant credits.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false
}Responses
200 Signup Session rotated
Headers: Set-Cookie, Cache-Control
200 response · application/json
{
"$ref": "#/components/schemas/LoginResponse"
}202 Email verification is pending; no new Session
Headers: Cache-Control
202 response · application/json
{
"type": "object",
"required": [
"pending"
],
"additionalProperties": false,
"properties": {
"pending": {
"type": "boolean",
"const": true
}
}
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected internal error occurred
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/password-resets
Request a password reset email
Always returns the same 202 response for a syntactically valid email regardless of account existence or lifecycle state. Only eligible active or locked identities receive mail.
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 320
}
}
}Responses
202 Request accepted. The response does not reveal whether an account exists.
Headers: Cache-Control, X-Request-Id
202 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"accepted"
],
"properties": {
"accepted": {
"type": "boolean",
"const": true
}
}
}422 Anonymous authentication request validation failed
Headers: Cache-Control, X-Request-Id
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Anonymous authentication rate limit exceeded
Headers: Cache-Control, Retry-After, X-Request-Id
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected anonymous authentication error occurred
Headers: Cache-Control, X-Request-Id
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 An anonymous authentication dependency is temporarily unavailable
Headers: Cache-Control, X-Request-Id
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/password-resets/confirm
Set a new password and revoke existing sessions
Atomically consumes the password-reset token, stores a new Argon2id credential, revokes every existing Session, and invalidates other password-reset tokens. It does not log the user in or create a Session.
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"token",
"password"
],
"properties": {
"token": {
"type": "string",
"minLength": 32,
"maxLength": 256,
"writeOnly": true
},
"password": {
"$ref": "#/components/schemas/Password"
}
}
}Responses
204 Password updated; existing sessions revoked
Headers: Cache-Control, X-Request-Id
410 One-time token is invalid, expired, invalidated, already used, or lost a concurrent confirmation race. Problem.code is `token_unavailable`.
Headers: Cache-Control, X-Request-Id
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Anonymous authentication request validation failed
Headers: Cache-Control, X-Request-Id
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Anonymous authentication rate limit exceeded
Headers: Cache-Control, Retry-After, X-Request-Id
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected anonymous authentication error occurred
Headers: Cache-Control, X-Request-Id
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 An anonymous authentication dependency is temporarily unavailable
Headers: Cache-Control, X-Request-Id
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/auth/sessions
List active sessions for the current user
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Sessions
Headers: Cache-Control, X-Request-Id
200 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Session"
}
}
}
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/auth/sessions
Revoke all sessions except the current one
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
204 Other sessions revoked
Headers: Cache-Control, X-Request-Id
401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/auth/sessions/{sessionId}
Revoke one session
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
sessionId · path · required
Schema
{
"type": "string",
"pattern": "^ses_"
}Responses
204 Session revoked. If it was the current Session, the cookie is cleared.
Headers: Set-Cookie, Cache-Control, X-Request-Id
401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/auth/re-authenticate
Verify the current password for a sensitive operation
Records a short-lived recent-auth proof on the current server-side session.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"password"
],
"properties": {
"password": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"writeOnly": true
}
}
}Responses
200 Session has recent authentication
Headers: Cache-Control, X-Request-Id
200 response · application/json
{
"$ref": "#/components/schemas/Reauthentication"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rate, concurrency, batch, or pending-job limit exceeded
Headers: Retry-After
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}PATCH/auth/password
Change the password and rotate the current session
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · 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
}
}
}Responses
204 Password changed; current session rotated and other sessions revoked when requested
Headers: Set-Cookie, Cache-Control, X-Request-Id
401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Account
GET/oauth/connections
List the current account's connected apps
Full session required. Empty when the account has no connected apps. Response is no-store.
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Connected apps
200 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OAuthConnection"
}
}
}
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/oauth/connections/{grantId}
Revoke a connected app and its dedicated API key
Full session, CSRF and allowed Origin required. Account ownership is enforced. Response is no-store.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
grantId · path · required
Schema
{
"type": "string",
"pattern": "^oag_[A-Za-z0-9_-]{8,}$"
}Responses
204 Authorization revoked
401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/account
Read account settings
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Account
200 response · application/json
{
"$ref": "#/components/schemas/Account"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}PATCH/account
Update profile settings
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"$ref": "#/components/schemas/UpdateAccountRequest"
}Responses
200 Updated account
200 response · application/json
{
"$ref": "#/components/schemas/Account"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/account
Schedule account deletion and revoke all existing sessions and API Keys
Administrator accounts must have their platform role revoked through the audited operator workflow before deletion can be scheduled. A unique active deletion request is the natural idempotency boundary. Concurrent authenticated schedules return the same request. After Session revocation, a lost response is recovered by logging into deletion_recovery mode and reading GET /account/deletion; revoked Sessions are never accepted for replay.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"password",
"confirmation"
],
"properties": {
"password": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"writeOnly": true
},
"confirmation": {
"type": "string",
"const": "DELETE"
}
}
}Responses
202 Deletion scheduled; active sessions and keys revoked
202 response · application/json
{
"$ref": "#/components/schemas/AccountDeletionRequest"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/account/deletion
Read the current account deletion request
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Current deletion request
200 response · application/json
{
"$ref": "#/components/schemas/AccountDeletionRequest"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/account/deletion
Cancel a scheduled deletion during the grace period
Uses a scheduled-to-cancelled compare-and-set. A processor race returns 409; after success the recovery Session is rotated and cannot replay the old transition.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
204 Deletion cancelled, account reactivated, and recovery Session rotated according to the legal-acceptance gate
Headers: Set-Cookie, Cache-Control, X-Request-Id
401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/account/legal-acceptances
Accept the currently published Terms and Privacy versions
Appends an immutable legal acceptance, clears the migration gate, and rotates the Session. Stale submitted versions are rejected.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"$ref": "#/components/schemas/LegalAcceptanceRequest"
}Responses
200 Legal acceptance recorded and Session rotated to full mode
Headers: Set-Cookie, Cache-Control, X-Request-Id
200 response · application/json
{
"$ref": "#/components/schemas/LoginResponse"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Onboarding
GET/onboarding
Read resumable onboarding progress
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Current onboarding state
Headers: Cache-Control, X-Request-Id
200 response · application/json
{
"$ref": "#/components/schemas/OnboardingProgress"
}401 Authentication required or invalid
Headers: Cache-Control, X-Request-Id
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected internal error occurred
Headers: Cache-Control, X-Request-Id
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or onboarding record is temporarily unavailable
Headers: Cache-Control, X-Request-Id
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}PATCH/onboarding
Advance onboarding without allowing progress to move backward
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"$ref": "#/components/schemas/UpdateOnboardingRequest"
}Responses
200 Updated onboarding state
Headers: Cache-Control, X-Request-Id
200 response · application/json
{
"$ref": "#/components/schemas/OnboardingProgress"
}401 Authentication required or invalid
Headers: Cache-Control, X-Request-Id
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
Headers: Cache-Control, X-Request-Id
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
Headers: Cache-Control, X-Request-Id
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
Headers: Cache-Control, X-Request-Id
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected internal error occurred
Headers: Cache-Control, X-Request-Id
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or onboarding record is temporarily unavailable
Headers: Cache-Control, X-Request-Id
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Overview
GET/overview
Read the account dashboard aggregate
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Account-scoped overview
Headers: Cache-Control, X-Request-Id
200 response · application/json
{
"$ref": "#/components/schemas/ConsoleOverview"
}401 Authentication required or invalid
Headers: Cache-Control, X-Request-Id
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected internal error occurred
Headers: Cache-Control, X-Request-Id
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or onboarding record is temporarily unavailable
Headers: Cache-Control, X-Request-Id
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}API Keys
GET/api-access/identity
Verify current API key ownership and recurring readiness
Free header-only API-key read. Returns public account/key IDs and authoritative ownership. No request body. Does not alter the existing /api-access metadata response. Shares the 120/minute account-read limit. Fail closed on unavailability; do not infer ownership from key prefix, plan, or local state. No query parameters are accepted. Responses are no-store.
Authentication: dataApiKey
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Verify current API key ownership and recurring readiness
200 response · application/json
{
"$ref": "#/components/schemas/APIKeyIdentity"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/api-keys
List API Key metadata
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 API Keys without secrets
200 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiKey"
}
}
}
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/api-keys
Create an API Key and reveal its secret once
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
Idempotency-Key · header · required
Schema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body · required
Schema · application/json
{
"$ref": "#/components/schemas/CreateApiKeyRequest"
}Responses
201 Created; the same idempotent replay may return the same encrypted response for five minutes
201 response · application/json
{
"$ref": "#/components/schemas/ApiKeyCreated"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/api-keys/{keyId}
Revoke an API Key
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
keyId · path · required
Schema
{
"type": "string",
"pattern": "^key_"
}Responses
204 Revoked
401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/api-keys/{keyId}/rotate
Create a replacement key and schedule old-key revocation
Creates a new key and keeps the old key active until revokeOldAt. By default, the overlap lasts 24 hours or until the old key expires, whichever is earlier. A custom revokeOldAt must be in the future, within seven days, and no later than the old key expiry.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
keyId · path · required
Schema
{
"type": "string",
"pattern": "^key_"
}Idempotency-Key · header · required
Schema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body · optional
Schema · 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."
}
}
}Responses
201 Replacement created; secret returned once
201 response · application/json
{
"$ref": "#/components/schemas/ApiKeyCreated"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/api-access
Read the calling API key's authorized sources and result origin
Free, header-only X-API-Key authentication. Returns only granted public source names and the configured signed-result storage origin (null if unavailable). No account ID, key ID, secret or storage credentials are returned. Local MCP revalidates this endpoint before every tool discovery and call, including cached result reads. No query parameters or request body are accepted. All /api-access routes share 120 requests per minute per client IP and return Cache-Control private, no-store. Normal key last-used tracking still occurs.
Authentication: dataApiKey
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Authorized public sources and result origin
200 response · application/json
{
"$ref": "#/components/schemas/ApiAccess"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Too many account reads; retry after the rate-limit window
503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Agent Connections
GET/agent-connections/capabilities
Discover protocol 2 onboarding availability
No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes.
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Discover protocol 2 onboarding availability
200 response · application/json
{
"$ref": "#/components/schemas/AgentCapabilities"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/registrations
Create or recover a temporary API-key connection
Persist the registration proof and exact input before POST. Same proof and body recover the same trial; changing input yields conflict. Temporary trial: 1 Credit, 72 hours, 1 request/second, batch size 1. Source scope limits remain authoritative on the server. No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes.
Authentication: agentRegistrationProof
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"$ref": "#/components/schemas/AgentRegistrationRequest"
}Responses
201 Create or recover a temporary API-key connection
201 response · application/json
{
"$ref": "#/components/schemas/AgentRegistration"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/agent-connections/owned
List browser-owned connections
No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes. Browser-owned operation. Full verified Session required; caller must not substitute an API key or proof.
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 List browser-owned connections
200 response · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {
"connections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentConnection"
}
}
},
"required": [
"connections"
]
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/agent-connections/{connectionId}
Read temporary connection status
No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes.
Authentication: agentSetupCredential
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
connectionId · path · required
Schema
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}Responses
200 Read temporary connection status
200 response · application/json
{
"$ref": "#/components/schemas/AgentConnectionResponse"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/agent-connections/{connectionId}
Revoke an owned connection
No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes. Browser-owned operation. Full verified Session required; caller must not substitute an API key or proof.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
connectionId · path · required
Schema
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}Origin · header · required
Schema
{
"type": "string"
}X-CSRF-Token · header · required
Schema
{
"type": "string"
}Responses
204 Revoke an owned connection
400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/agent-connections/{connectionId}/identity
Verify the current data API key for a connection
No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes.
Authentication: agentIdentityKey
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
connectionId · path · required
Schema
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}Responses
200 Verify the current data API key for a connection
200 response · application/json
{
"$ref": "#/components/schemas/AgentConnectionResponse"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/agent-connections/{connectionId}/onboarding
Read recoverable onboarding state
No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes.
Authentication: agentHandoffProof
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
connectionId · path · required
Schema
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}Responses
200 Read recoverable onboarding state
200 response · application/json
{
"$ref": "#/components/schemas/AgentOnboardingStatus"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/{connectionId}/claims
Create a browser approval claim
Open claimPath on a trusted FlashData web origin and display the code separately. Never place credentials or the confirmation code in the URL. No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes.
Authentication: agentSetupCredential
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
connectionId · path · required
Schema
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {},
"required": []
}Responses
201 Create a browser approval claim
201 response · application/json
{
"$ref": "#/components/schemas/AgentClaim"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/claims/{claimId}/confirm
Confirm the claim code in a verified browser session
No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes. Browser-owned operation. Full verified Session required; caller must not substitute an API key or proof.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
claimId · path · required
Schema
{
"type": "string",
"pattern": "^acl_[A-Za-z0-9_-]{8,100}$"
}Origin · header · required
Schema
{
"type": "string"
}X-CSRF-Token · header · required
Schema
{
"type": "string"
}Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"pattern": "^\\d{8}$"
}
},
"required": [
"code"
]
}Responses
200 Confirm the claim code in a verified browser session
200 response · application/json
{
"$ref": "#/components/schemas/AgentBrowserClaim"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/agent-connections/claims/{claimId}
Read a confirmed claim in its browser session
No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes. Browser-owned operation. Full verified Session required; caller must not substitute an API key or proof.
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
claimId · path · required
Schema
{
"type": "string",
"pattern": "^acl_[A-Za-z0-9_-]{8,100}$"
}Responses
200 Read a confirmed claim in its browser session
200 response · application/json
{
"$ref": "#/components/schemas/AgentClaimView"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/claims/{claimId}/approve
Approve reduced scopes and account-balance funding
No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes. Browser-owned operation. Full verified Session required; caller must not substitute an API key or proof.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
claimId · path · required
Schema
{
"type": "string",
"pattern": "^acl_[A-Za-z0-9_-]{8,100}$"
}Origin · header · required
Schema
{
"type": "string"
}X-CSRF-Token · header · required
Schema
{
"type": "string"
}Request body · required
Schema · application/json
{
"$ref": "#/components/schemas/AgentApproval"
}Responses
200 Approve reduced scopes and account-balance funding
200 response · 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 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/{connectionId}/handoff
Recover the approved owner API key
Candidate key expires in 24 hours until installation ACK. Persist atomically, reload in a fresh process and verify identity before ACK. A repeated delivery recovers the same candidate; confirmed delivery returns a receipt without credentials. No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes.
Authentication: agentHandoffProof
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
connectionId · path · required
Schema
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {},
"required": []
}Responses
200 Recover the approved owner API key
200 response · application/json
{
"$ref": "#/components/schemas/AgentHandoff"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/agent-connections/{connectionId}/handoff/ack
Acknowledge verified owner-key installation
Caller must already have saved the candidate and independently verified it in a fresh process. Successful ACK marks installed, removes the candidate key expiry and deletes recoverable credential material. Repeated ACK is idempotent. No query parameters are accepted. Responses are no-store. Agent routes are management-only and feature-gated; deployments can return 404 when disabled. X-API-Key is forbidden on agent routes.
Authentication: agentHandoffProof
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
connectionId · path · required
Schema
{
"type": "string",
"pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"properties": {
"apiKey": {
"type": "string"
}
},
"required": [
"apiKey"
]
}Responses
200 Acknowledge verified owner-key installation
200 response · application/json
{
"$ref": "#/components/schemas/AgentHandoff"
}400 Rejected request; inspect the Problem code. Never retry a mutation blindly.
400 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}401 Rejected request; inspect the Problem code. Never retry a mutation blindly.
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Rejected request; inspect the Problem code. Never retry a mutation blindly.
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Rejected request; inspect the Problem code. Never retry a mutation blindly.
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Rejected request; inspect the Problem code. Never retry a mutation blindly.
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Rejected request; inspect the Problem code. Never retry a mutation blindly.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Rejected request; inspect the Problem code. Never retry a mutation blindly.
429 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 Rejected request; inspect the Problem code. Never retry a mutation blindly.
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Catalog
GET/catalog/sources
List public source capabilities without account-specific pricing
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Public source catalog
Headers: Cache-Control
200 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DataSource"
}
}
}
}GET/plans
List public USD plans and prices
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Public plan catalog
Headers: Cache-Control
200 response · application/json
{
"$ref": "#/components/schemas/PlanCatalog"
}GET/legal/current
Read the current Terms and Privacy versions required for signup
Authentication: Public
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Current legal version catalog
Headers: Cache-Control
200 response · application/json
{
"$ref": "#/components/schemas/PublicLegalVersions"
}Billing
GET/billing/subscription
Read the effective Stripe subscription
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Subscription or PAYG entitlement
200 response · application/json
{
"$ref": "#/components/schemas/Subscription"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/billing/checkout-sessions
Create a Stripe-hosted Checkout Session
Subscriptions and published credit packs use priceId. A custom top-up uses amountMinor instead (USD cents, $10 to $999,999.99); the server calculates credits at the fixed credit value and creates a private one-time Stripe price. Product, provider price, currency, success URL and cancel URL are never accepted from the browser. Credits are granted only after a verified paid event for the quoted amount.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
Idempotency-Key · header · required
Schema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body · required
Schema · 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"
}
}
}
]
}Responses
201 Stripe Checkout Session
201 response · application/json
{
"$ref": "#/components/schemas/HostedSession"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}502 An upstream provider failed
502 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 The billing catalog or provider is not configured or is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/billing/subscription-changes
Upgrade the current Stripe subscription to a higher published price
The server verifies that the FlashData price is active, available in the current livemode, USD-denominated, recurring, the same interval, and strictly more expensive than the current subscription price. Product, provider price, currency and proration options are never accepted from the browser. Local entitlement and credits change only after a verified provider event is projected.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
Idempotency-Key · header · required
Schema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"priceId"
],
"properties": {
"priceId": {
"type": "string",
"pattern": "^prc_"
}
}
}Responses
201 Subscription change submitted to Stripe
201 response · application/json
{
"$ref": "#/components/schemas/SubscriptionChange"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}502 An upstream provider failed
502 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 The billing catalog or provider is not configured or is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/billing/portal-sessions
Create a Stripe Customer Portal Session
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
Idempotency-Key · header · required
Schema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Responses
201 Stripe Customer Portal Session
201 response · application/json
{
"$ref": "#/components/schemas/HostedSession"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}502 An upstream provider failed
502 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 The billing catalog or provider is not configured or is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/billing/subscription-cancellation
Schedule or undo cancellation of the current paid subscription
Setting cancelAtPeriodEnd to true schedules cancellation at the current billing period end; false keeps the subscription. Entitlements update after a verified Stripe subscription event. This endpoint never cancels immediately or issues a refund.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
Idempotency-Key · header · required
Schema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body · required
Schema · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"cancelAtPeriodEnd"
],
"properties": {
"cancelAtPeriodEnd": {
"type": "boolean"
}
}
}Responses
202 Cancellation update submitted to Stripe
202 response · application/json
SubscriptionCancellationChange
{
"$ref": "#/components/schemas/SubscriptionCancellationChange"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}502 An upstream provider failed
502 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 The billing catalog or provider is not configured or is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/billing/invoices
List Stripe invoice projections
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
cursor · query · optional
Schema
{
"type": "string",
"maxLength": 512
}limit · query · optional
Schema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}Responses
200 Invoices
401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/billing/payments
List account-scoped top-up and refund payment projections
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
cursor · query · optional
Schema
{
"type": "string",
"maxLength": 512
}limit · query · optional
Schema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}Responses
200 One-time payment history without provider secrets
200 response · application/json
{
"$ref": "#/components/schemas/BillingPaymentPage"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Credits
GET/api-access/balance
Read the live account balance using an API key
Read the current credit balance shared by all API keys in your account. Active reservations can reduce the available balance. This request costs no Credits and takes no query parameters or body. Responses are private and are not cached; account-read rate limits apply.
Authentication: dataApiKey
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Signed balance and nonnegative available Credits
200 response · application/json
{
"$ref": "#/components/schemas/ApiAccessBalance"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Too many account reads; retry after the rate-limit window
503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/api-access/pricing
Read actual account prices for sources authorized by the API key
Read your account rates for sources allowed by the API key. A null price means that source is unavailable. request_count counts queries, not returned items; download rates are per TB (10^12 bytes). Estimates do not reserve Credits or capacity. This request costs no Credits. Responses are private and are not cached; account-read rate limits apply.
Authentication: dataApiKey
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
source · query · optional
A source granted to this key; omit to read all granted sources.
Schema
{
"$ref": "#/components/schemas/ApiAccessSource"
}request_count · query · optional
Decimal integer number of calls; does not estimate download size.
Schema
{
"type": "integer",
"minimum": 1,
"maximum": 100000,
"default": 1
}Responses
200 Account plan and source-specific prices
200 response · application/json
{
"$ref": "#/components/schemas/ApiAccessPricing"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Too many account reads; retry after the rate-limit window
503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/api-access/limits
Read account plan limits and current pending jobs using an API key
Read your concurrency, batch-size and pending-job limits, plus the current pending count. These values help plan requests but do not reserve capacity. This request costs no Credits and takes no query parameters or body. Responses are private and are not cached; account-read rate limits apply.
Authentication: dataApiKey
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Plan ceilings and current pending count
200 response · application/json
{
"$ref": "#/components/schemas/ApiAccessLimits"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Too many account reads; retry after the rate-limit window
503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/usage
Read account usage for sources authorized by the API key
Free read, authenticated only by X-API-Key. Includes all account keys but only sources granted to the calling key. Does not return query text, keys, payment details or other accounts. Defaults to seven days; maximum 31 days. Dates must use UTC Z timestamps. From is inclusive and to exclusive; both are rounded down to minutes. With from alone, to defaults to from + 7 days. With neither, to is the start of the next minute. Aggregates are eventually consistent; even updating=false does not guarantee all recent events are ingested. Read limit: 60 requests per minute per client IP.
Authentication: dataApiKey
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
source · query · optional
An exact catalog source granted to the calling key; omitted means all granted sources.
Schema
{
"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 · optional
Schema
{
"type": "string",
"format": "date-time"
}to · query · optional
Schema
{
"type": "string",
"format": "date-time"
}Responses
200 Scoped request counts and charged Credits, with freshness information
200 response · application/json
{
"$ref": "#/components/schemas/ApiKeyUsage"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}429 Too many usage reads; retry after the rate-limit window
503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/credits/balance
Read current available and reserved credits
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Credit balance
200 response · application/json
{
"$ref": "#/components/schemas/CreditBalance"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/credits/policy
Read the effective account credit grant and charging policy
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Effective credit policy
200 response · application/json
{
"$ref": "#/components/schemas/CreditPolicy"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/credits/transactions
List credit ledger entries
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
cursor · query · optional
Schema
{
"type": "string",
"maxLength": 512
}limit · query · optional
Schema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}type · query · optional
Schema
{
"$ref": "#/components/schemas/CreditEntryType"
}Responses
200 Ledger entries
200 response · application/json
{
"allOf": [
{
"$ref": "#/components/schemas/Page"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreditTransaction"
}
}
}
}
]
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Trial Credits
GET/trial-credit-request
Read Trial Credit eligibility and the account's lifetime request
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Current eligibility, configured grant, and request state
Headers: Cache-Control
200 response · application/json
{
"$ref": "#/components/schemas/TrialCreditState"
}401 Authentication required or invalid
Headers: Cache-Control, X-Request-Id
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected internal error occurred
Headers: Cache-Control, X-Request-Id
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or onboarding record is temporarily unavailable
Headers: Cache-Control, X-Request-Id
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/trial-credit-request
Submit the account's one lifetime Trial Credit request
The trial amount and use case are saved when you submit the request.
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
Idempotency-Key · header · required
Schema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body · optional
Schema · application/json
{
"type": "object",
"additionalProperties": false
}Responses
201 Trial Credit request created and automatically approved for eligible verified accounts, regardless of email provider
Headers: Cache-Control
201 response · application/json
{
"$ref": "#/components/schemas/TrialCreditState"
}401 Authentication required or invalid
Headers: Cache-Control, X-Request-Id
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}403 Authenticated but not permitted, or CSRF validation failed
Headers: Cache-Control, X-Request-Id
403 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
Headers: Cache-Control, X-Request-Id
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
Headers: Cache-Control, X-Request-Id
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}500 An unexpected internal error occurred
Headers: Cache-Control, X-Request-Id
500 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or onboarding record is temporarily unavailable
Headers: Cache-Control, X-Request-Id
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Delivery
GET/delivery/webhooks
List saved completion callback URLs
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Responses
200 Callback URLs
200 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DeliveryWebhook"
}
}
}
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/delivery/webhooks
Save a completion callback URL
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · application/json
{
"$ref": "#/components/schemas/CreateDeliveryWebhookRequest"
}Responses
201 Created
201 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"webhook"
],
"properties": {
"webhook": {
"$ref": "#/components/schemas/DeliveryWebhook"
}
}
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}DELETE/delivery/webhooks/{webhookId}
Remove a completion callback URL
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
webhookId · path · required
Schema
{
"type": "string",
"pattern": "^cbk_[A-Za-z0-9_-]{8,}$"
}Responses
204 Removed
401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}POST/delivery/webhooks/{webhookId}/test
Send a sample download-complete payload
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
webhookId · path · required
Schema
{
"type": "string",
"pattern": "^cbk_[A-Za-z0-9_-]{8,}$"
}Responses
200 Test attempted
200 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"statusCode",
"webhook"
],
"properties": {
"statusCode": {
"type": "integer",
"minimum": 0
},
"webhook": {
"$ref": "#/components/schemas/DeliveryWebhook"
}
}
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Jobs
For submission, status and result examples, see Realtime and async · Batch requests.
GET/jobs
List Data API jobs for the current workspace
Cursor-paginated active and archived history. Defaults to the last seven days; each UTC date range is limited to 31 days. From is inclusive and to is exclusive, at minute precision. Summaries are maintained asynchronously and may lag ingestion.
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
cursor · query · optional
Schema
{
"type": "string",
"minLength": 1,
"maxLength": 512
}limit · query · optional
Schema
{
"type": "integer",
"minimum": 1,
"maximum": 50
}source · query · optional
Schema
{
"type": "string",
"pattern": "^(google|youtube|google_[a-z]+|youtube_[a-z_]+)$"
}status · query · optional
Schema
{
"type": "string",
"enum": [
"completed",
"failed",
"pending",
"processing"
]
}mode · query · optional
Schema
{
"type": "string",
"enum": [
"async",
"batch",
"realtime"
]
}from · query · optional
Schema
{
"type": "string",
"format": "date-time"
}to · query · optional
Schema
{
"type": "string",
"format": "date-time"
}Responses
200 Job page
200 response · 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 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/jobs/{jobId}
Read one Data API job
Read job.status to check progress and job.error if processing failed. JSON is the default; use Accept: text/plain for readable text. X-Respond-With is ignored here. Follow Retry-After when provided before checking again.
Authentication: cookieSession or dataApiKey
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
Accept · header · optional
application/json returns the original structured response; text/plain returns the same fields as indented plain text. Standard media ranges and q weights are supported; missing Accept or a global wildcard defaults to JSON. X-Respond-With is ignored on submission and job-status endpoints. Errors remain structured JSON. Both response types use UTF-8; an explicit charset=utf-8 parameter is supported.
Schema
{
"type": "string"
}jobId · path · required
Schema
{
"type": "string",
"pattern": "^job_[A-Za-z0-9_-]+$"
}Responses
200 Job detail
200 response · application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"job"
],
"properties": {
"job": {
"$ref": "#/components/schemas/ConsoleJob"
}
}
}200 response · text/plain
{
"type": "string"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}406 Neither application/json nor text/plain is acceptable; response is JSON
406 response · application/json
{
"$ref": "#/components/schemas/QueryRepresentationError"
}GET/jobs/{jobId}/results
Download a completed async result
By default, authenticates access and redirects to a short-lived private R2 URL; clients receive the original JSON directly from R2. Accept: text/plain independently returns HTTP 200 with the original result fields as indented plain text. X-Respond-With: markdown selects Markdown content: application/json wraps it in content alongside the original metadata, replacing results; text/plain returns metadata followed by Markdown. Missing Accept or a global wildcard defaults to JSON. Formatting does not submit another query or charge query credits. Stored results expire 24 hours after completion. Errors remain structured JSON.
Authentication: cookieSession or dataApiKey
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
X-Respond-With · header · optional
Set to markdown to return result content as Markdown. Omit to retain the original result fields. Accept independently selects JSON or plain text. Only realtime queries and completed job result reads support this header. It does not change job submissions, status, account APIs, callbacks, Bulk files, binary downloads, or MCP protocol responses.
Schema
{
"type": "string",
"enum": [
"markdown"
]
}Accept · header · optional
Select application/json or text/plain independently of X-Respond-With. Without X-Respond-With, text/plain returns the original fields with indentation; JSON retains the original response fields (completed-result reads redirect to storage). With markdown, JSON returns content plus metadata and plain text returns metadata followed by Markdown. Standard media ranges and q weights are supported; missing Accept or a global wildcard defaults to JSON. Both response types use UTF-8; an explicit charset=utf-8 parameter is supported.
Schema
{
"type": "string"
}jobId · path · required
Schema
{
"type": "string",
"pattern": "^job_[A-Za-z0-9_-]+$"
}Responses
200 Plain-text original fields or Markdown returned directly; original JSON from R2 after following the default redirect
200 response · application/json
{
"anyOf": [
{
"$ref": "#/components/schemas/MarkdownQueryResult"
},
{
"type": "object",
"additionalProperties": true
}
]
}200 response · text/plain
{
"type": "string"
}302 Redirect to original JSON in private R2 storage when JSON is selected without X-Respond-With
Headers: Location
400 Unsupported X-Respond-With value; response is JSON
400 response · application/json
{
"$ref": "#/components/schemas/QueryRepresentationError"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}406 Neither application/json nor text/plain is acceptable; response is JSON
406 response · application/json
{
"$ref": "#/components/schemas/QueryRepresentationError"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 Result expired
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 The job failed. The response includes the saved failure reason in detail when available.
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Bulk processing API
Bulk endpoints have a dedicated reference with parameters, request examples and response schemas. Open Bulk processing API
GET /v2/bulk-jobs· List bulk YouTube jobsPOST /v2/bulk-jobs· Create a Bulk job and get a file upload URLGET /v2/bulk-jobs/{bulkId}· Read bulk job progress and aggregate countsPATCH /v2/bulk-jobs/{bulkId}· Change settings for videos that have not startedDELETE /v2/bulk-jobs/{bulkId}· Cancel a Bulk jobPOST /v2/bulk-jobs/{bulkId}/start· Start scanning an uploaded YouTube ID filePOST /v2/bulk-jobs/{bulkId}/pause· Pause a Bulk jobPOST /v2/bulk-jobs/{bulkId}/resume· Resume a manually or automatically paused bulk jobGET /v2/bulk-jobs/{bulkId}/results· Download the completed bulk manifestGET /v2/bulk-jobs/{bulkId}/results/{partNumber}· Download one gzip-compressed NDJSON bulk result part
Playground
POST/playground/run
Run a playground query as the current workspace
Authentication: cookieSession + csrfToken
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Request body · required
Schema · 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
}
}
}Responses
200 Upstream Data API response captured for the playground
200 response · 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 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}422 Request validation failed
422 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}GET/playground/jobs/{jobId}/download
Download a completed Playground artifact in the current browser
Authentication: cookieSession
Server: https://api.flashdata.dev/v2
Server: http://localhost:5000/v2
Parameters
jobId · path · required
Schema
{
"type": "string",
"pattern": "^job_[A-Za-z0-9_-]+$"
}Responses
200 Temporary browser-download artifact
Headers: Content-Disposition, Content-Length
200 response · application/octet-stream
{
"type": "string",
"format": "binary"
}401 Authentication required or invalid
401 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}404 Resource not found or not owned by the caller
404 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}409 Resource state or idempotency conflict
409 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}410 The temporary artifact has expired
410 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}503 A required dependency or catalog is temporarily unavailable
503 response · application/problem+json
{
"$ref": "#/components/schemas/Problem"
}Schema definitions
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."
}
}
}