Skip to content
EN
Get API key
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.

Check the current key · Bash
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

SchemeRequirement
dataApiKey

X-API-Key · header

FlashData API key. Job access is restricted to the key's source scopes.

cookieSession

__Host-fd_session · cookie

Opaque Web session. The browser cannot read this cookie.

csrfToken

X-CSRF-Token · header

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

Health

200 response
{
  "$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

PublicStatus

200 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^fdo_[A-Za-z0-9_-]{43}$"
}

Responses

200 Requested app permissions

200 response · application/json

OAuthConsent

200 response
{
  "$ref": "#/components/schemas/OAuthConsent"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Request expired, used, or bound to another session

410 response · application/problem+json

Problem

410 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^fdo_[A-Za-z0-9_-]{43}$"
}

Request body · required

Schema · application/json
Schema
{
  "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
200 response
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "redirectUrl"
  ],
  "properties": {
    "redirectUrl": {
      "type": "string",
      "format": "uri"
    }
  }
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Authorization request unavailable; start a new connection

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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

RegisterRequest

Schema
{
  "$ref": "#/components/schemas/RegisterRequest"
}

Responses

201 Account created; email verification required

Headers: Cache-Control, X-Request-Id

201 response · application/json

RegisterResponse

201 response
{
  "$ref": "#/components/schemas/RegisterResponse"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rate, concurrency, batch, or pending-job limit exceeded

Headers: Retry-After

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected internal error occurred

500 response · application/problem+json

Problem

500 response
{
  "$ref": "#/components/schemas/Problem"
}

503 A required dependency or catalog is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$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

LoginRequest

Schema
{
  "$ref": "#/components/schemas/LoginRequest"
}

Responses

200 Authenticated

Headers: Set-Cookie, Cache-Control, X-Request-Id

200 response · application/json

LoginResponse

200 response
{
  "$ref": "#/components/schemas/LoginResponse"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$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

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

423 Account temporarily locked

Headers: Retry-After

423 response · application/problem+json

Problem

423 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rate, concurrency, batch, or pending-job limit exceeded

Headers: Retry-After

429 response · application/problem+json

Problem

429 response
{
  "$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

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$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

Account

200 response
{
  "$ref": "#/components/schemas/Account"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$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
200 response
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "csrfToken"
  ],
  "properties": {
    "csrfToken": {
      "type": "string",
      "minLength": 32,
      "readOnly": true
    }
  }
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$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
Schema
{
  "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
202 response
{
  "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

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Anonymous authentication rate limit exceeded

Headers: Cache-Control, Retry-After, X-Request-Id

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected anonymous authentication error occurred

Headers: Cache-Control, X-Request-Id

500 response · application/problem+json

Problem

500 response
{
  "$ref": "#/components/schemas/Problem"
}

503 An anonymous authentication dependency is temporarily unavailable

Headers: Cache-Control, X-Request-Id

503 response · application/problem+json

Problem

503 response
{
  "$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

TokenRequest

Schema
{
  "$ref": "#/components/schemas/TokenRequest"
}

Responses

200 Account activated

Headers: Set-Cookie, Cache-Control, X-Request-Id

200 response · application/json

Account

200 response
{
  "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

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Anonymous authentication request validation failed

Headers: Cache-Control, X-Request-Id

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Anonymous authentication rate limit exceeded

Headers: Cache-Control, Retry-After, X-Request-Id

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected anonymous authentication error occurred

Headers: Cache-Control, X-Request-Id

500 response · application/problem+json

Problem

500 response
{
  "$ref": "#/components/schemas/Problem"
}

503 An anonymous authentication dependency is temporarily unavailable

Headers: Cache-Control, X-Request-Id

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "object",
  "additionalProperties": false
}

Responses

200 Signup Session rotated

Headers: Set-Cookie, Cache-Control

200 response · application/json

LoginResponse

200 response
{
  "$ref": "#/components/schemas/LoginResponse"
}

202 Email verification is pending; no new Session

Headers: Cache-Control

202 response · application/json
202 response
{
  "type": "object",
  "required": [
    "pending"
  ],
  "additionalProperties": false,
  "properties": {
    "pending": {
      "type": "boolean",
      "const": true
    }
  }
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected internal error occurred

500 response · application/problem+json

Problem

500 response
{
  "$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
Schema
{
  "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
202 response
{
  "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

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Anonymous authentication rate limit exceeded

Headers: Cache-Control, Retry-After, X-Request-Id

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected anonymous authentication error occurred

Headers: Cache-Control, X-Request-Id

500 response · application/problem+json

Problem

500 response
{
  "$ref": "#/components/schemas/Problem"
}

503 An anonymous authentication dependency is temporarily unavailable

Headers: Cache-Control, X-Request-Id

503 response · application/problem+json

Problem

503 response
{
  "$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

Password

Schema
{
  "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

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Anonymous authentication request validation failed

Headers: Cache-Control, X-Request-Id

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Anonymous authentication rate limit exceeded

Headers: Cache-Control, Retry-After, X-Request-Id

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected anonymous authentication error occurred

Headers: Cache-Control, X-Request-Id

500 response · application/problem+json

Problem

500 response
{
  "$ref": "#/components/schemas/Problem"
}

503 An anonymous authentication dependency is temporarily unavailable

Headers: Cache-Control, X-Request-Id

503 response · application/problem+json

Problem

503 response
{
  "$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

Session

200 response
{
  "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

Problem

401 response
{
  "$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

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$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
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

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

503 A required dependency or catalog is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "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

Reauthentication

200 response
{
  "$ref": "#/components/schemas/Reauthentication"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rate, concurrency, batch, or pending-job limit exceeded

Headers: Retry-After

429 response · application/problem+json

Problem

429 response
{
  "$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

Password

Schema
{
  "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

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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

OAuthConnection

200 response
{
  "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

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^oag_[A-Za-z0-9_-]{8,}$"
}

Responses

204 Authorization revoked

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$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

Account

200 response
{
  "$ref": "#/components/schemas/Account"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$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

UpdateAccountRequest

Schema
{
  "$ref": "#/components/schemas/UpdateAccountRequest"
}

Responses

200 Updated account

200 response · application/json

Account

200 response
{
  "$ref": "#/components/schemas/Account"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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
Schema
{
  "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

AccountDeletionRequest

202 response
{
  "$ref": "#/components/schemas/AccountDeletionRequest"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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

AccountDeletionRequest

200 response
{
  "$ref": "#/components/schemas/AccountDeletionRequest"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$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

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$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

LegalAcceptanceRequest

Schema
{
  "$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

LoginResponse

200 response
{
  "$ref": "#/components/schemas/LoginResponse"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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

OnboardingProgress

200 response
{
  "$ref": "#/components/schemas/OnboardingProgress"
}

401 Authentication required or invalid

Headers: Cache-Control, X-Request-Id

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected internal error occurred

Headers: Cache-Control, X-Request-Id

500 response · application/problem+json

Problem

500 response
{
  "$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

Problem

503 response
{
  "$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

UpdateOnboardingRequest

Schema
{
  "$ref": "#/components/schemas/UpdateOnboardingRequest"
}

Responses

200 Updated onboarding state

Headers: Cache-Control, X-Request-Id

200 response · application/json

OnboardingProgress

200 response
{
  "$ref": "#/components/schemas/OnboardingProgress"
}

401 Authentication required or invalid

Headers: Cache-Control, X-Request-Id

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

Headers: Cache-Control, X-Request-Id

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

Headers: Cache-Control, X-Request-Id

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

Headers: Cache-Control, X-Request-Id

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected internal error occurred

Headers: Cache-Control, X-Request-Id

500 response · application/problem+json

Problem

500 response
{
  "$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

Problem

503 response
{
  "$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

ConsoleOverview

200 response
{
  "$ref": "#/components/schemas/ConsoleOverview"
}

401 Authentication required or invalid

Headers: Cache-Control, X-Request-Id

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected internal error occurred

Headers: Cache-Control, X-Request-Id

500 response · application/problem+json

Problem

500 response
{
  "$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

Problem

503 response
{
  "$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

APIKeyIdentity

200 response
{
  "$ref": "#/components/schemas/APIKeyIdentity"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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

ApiKey

200 response
{
  "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

Problem

401 response
{
  "$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
Schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255
}

Request body · required

Schema · application/json

CreateApiKeyRequest

Schema
{
  "$ref": "#/components/schemas/CreateApiKeyRequest"
}

Responses

201 Created; the same idempotent replay may return the same encrypted response for five minutes

201 response · application/json

ApiKeyCreated

201 response
{
  "$ref": "#/components/schemas/ApiKeyCreated"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

503 A required dependency or catalog is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^key_"
}

Responses

204 Revoked

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

503 A required dependency or catalog is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^key_"
}

Idempotency-Key · header · required

Schema
Schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255
}

Request body · optional

Schema · application/json
Schema
{
  "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

ApiKeyCreated

201 response
{
  "$ref": "#/components/schemas/ApiKeyCreated"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

503 A required dependency or catalog is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$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

ApiAccess

200 response
{
  "$ref": "#/components/schemas/ApiAccess"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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

Problem

503 response
{
  "$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

AgentCapabilities

200 response
{
  "$ref": "#/components/schemas/AgentCapabilities"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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

AgentRegistrationRequest

Schema
{
  "$ref": "#/components/schemas/AgentRegistrationRequest"
}

Responses

201 Create or recover a temporary API-key connection

201 response · application/json

AgentRegistration

201 response
{
  "$ref": "#/components/schemas/AgentRegistration"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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

AgentConnection

200 response
{
  "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

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}

Responses

200 Read temporary connection status

200 response · application/json

AgentConnectionResponse

200 response
{
  "$ref": "#/components/schemas/AgentConnectionResponse"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}

Origin · header · required

Schema
Schema
{
  "type": "string"
}

X-CSRF-Token · header · required

Schema
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

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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
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

AgentConnectionResponse

200 response
{
  "$ref": "#/components/schemas/AgentConnectionResponse"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}

Responses

200 Read recoverable onboarding state

200 response · application/json

AgentOnboardingStatus

200 response
{
  "$ref": "#/components/schemas/AgentOnboardingStatus"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}

Request body · required

Schema · application/json
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}

Responses

201 Create a browser approval claim

201 response · application/json

AgentClaim

201 response
{
  "$ref": "#/components/schemas/AgentClaim"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^acl_[A-Za-z0-9_-]{8,100}$"
}

Origin · header · required

Schema
Schema
{
  "type": "string"
}

X-CSRF-Token · header · required

Schema
Schema
{
  "type": "string"
}

Request body · required

Schema · application/json
Schema
{
  "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

AgentBrowserClaim

200 response
{
  "$ref": "#/components/schemas/AgentBrowserClaim"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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
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

AgentClaimView

200 response
{
  "$ref": "#/components/schemas/AgentClaimView"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^acl_[A-Za-z0-9_-]{8,100}$"
}

Origin · header · required

Schema
Schema
{
  "type": "string"
}

X-CSRF-Token · header · required

Schema
Schema
{
  "type": "string"
}

Request body · required

Schema · application/json

AgentApproval

Schema
{
  "$ref": "#/components/schemas/AgentApproval"
}

Responses

200 Approve reduced scopes and account-balance funding

200 response · application/json

AgentConnection

200 response
{
  "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

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}

Request body · required

Schema · application/json
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {},
  "required": []
}

Responses

200 Recover the approved owner API key

200 response · application/json

AgentHandoff

200 response
{
  "$ref": "#/components/schemas/AgentHandoff"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^acn_[A-Za-z0-9_-]{8,100}$"
}

Request body · required

Schema · application/json
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "apiKey": {
      "type": "string"
    }
  },
  "required": [
    "apiKey"
  ]
}

Responses

200 Acknowledge verified owner-key installation

200 response · application/json

AgentHandoff

200 response
{
  "$ref": "#/components/schemas/AgentHandoff"
}

400 Rejected request; inspect the Problem code. Never retry a mutation blindly.

400 response · application/problem+json

Problem

400 response
{
  "$ref": "#/components/schemas/Problem"
}

401 Rejected request; inspect the Problem code. Never retry a mutation blindly.

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Rejected request; inspect the Problem code. Never retry a mutation blindly.

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Rejected request; inspect the Problem code. Never retry a mutation blindly.

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Rejected request; inspect the Problem code. Never retry a mutation blindly.

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Rejected request; inspect the Problem code. Never retry a mutation blindly.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

429 Rejected request; inspect the Problem code. Never retry a mutation blindly.

429 response · application/problem+json

Problem

429 response
{
  "$ref": "#/components/schemas/Problem"
}

503 Rejected request; inspect the Problem code. Never retry a mutation blindly.

503 response · application/problem+json

Problem

503 response
{
  "$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

DataSource

200 response
{
  "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

PlanCatalog

200 response
{
  "$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

PublicLegalVersions

200 response
{
  "$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

Subscription

200 response
{
  "$ref": "#/components/schemas/Subscription"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$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
Schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255
}

Request body · required

Schema · application/json
Schema
{
  "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

HostedSession

201 response
{
  "$ref": "#/components/schemas/HostedSession"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

502 An upstream provider failed

502 response · application/problem+json

Problem

502 response
{
  "$ref": "#/components/schemas/Problem"
}

503 The billing catalog or provider is not configured or is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255
}

Request body · required

Schema · application/json
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "priceId"
  ],
  "properties": {
    "priceId": {
      "type": "string",
      "pattern": "^prc_"
    }
  }
}

Responses

201 Subscription change submitted to Stripe

201 response · application/json

SubscriptionChange

201 response
{
  "$ref": "#/components/schemas/SubscriptionChange"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

502 An upstream provider failed

502 response · application/problem+json

Problem

502 response
{
  "$ref": "#/components/schemas/Problem"
}

503 The billing catalog or provider is not configured or is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255
}

Responses

201 Stripe Customer Portal Session

201 response · application/json

HostedSession

201 response
{
  "$ref": "#/components/schemas/HostedSession"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

502 An upstream provider failed

502 response · application/problem+json

Problem

502 response
{
  "$ref": "#/components/schemas/Problem"
}

503 The billing catalog or provider is not configured or is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255
}

Request body · required

Schema · application/json
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "cancelAtPeriodEnd"
  ],
  "properties": {
    "cancelAtPeriodEnd": {
      "type": "boolean"
    }
  }
}

Responses

202 Cancellation update submitted to Stripe

202 response · application/json

SubscriptionCancellationChange

202 response
{
  "$ref": "#/components/schemas/SubscriptionCancellationChange"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

502 An upstream provider failed

502 response · application/problem+json

Problem

502 response
{
  "$ref": "#/components/schemas/Problem"
}

503 The billing catalog or provider is not configured or is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "maxLength": 512
}

limit · query · optional

Schema
Schema
{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 50
}

Responses

200 Invoices

200 response · application/json

Invoice · Page

200 response
{
  "allOf": [
    {
      "$ref": "#/components/schemas/Page"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Invoice"
          }
        }
      }
    }
  ]
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$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
Schema
{
  "type": "string",
  "maxLength": 512
}

limit · query · optional

Schema
Schema
{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 50
}

Responses

200 One-time payment history without provider secrets

200 response · application/json

BillingPaymentPage

200 response
{
  "$ref": "#/components/schemas/BillingPaymentPage"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$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

ApiAccessBalance

200 response
{
  "$ref": "#/components/schemas/ApiAccessBalance"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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

Problem

503 response
{
  "$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

ApiAccessSource

Schema
{
  "$ref": "#/components/schemas/ApiAccessSource"
}

request_count · query · optional

Decimal integer number of calls; does not estimate download size.

Schema
Schema
{
  "type": "integer",
  "minimum": 1,
  "maximum": 100000,
  "default": 1
}

Responses

200 Account plan and source-specific prices

200 response · application/json

ApiAccessPricing

200 response
{
  "$ref": "#/components/schemas/ApiAccessPricing"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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

Problem

503 response
{
  "$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

ApiAccessLimits

200 response
{
  "$ref": "#/components/schemas/ApiAccessLimits"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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

Problem

503 response
{
  "$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
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
Schema
{
  "type": "string",
  "format": "date-time"
}

to · query · optional

Schema
Schema
{
  "type": "string",
  "format": "date-time"
}

Responses

200 Scoped request counts and charged Credits, with freshness information

200 response · application/json

ApiKeyUsage

200 response
{
  "$ref": "#/components/schemas/ApiKeyUsage"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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

Problem

503 response
{
  "$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

CreditBalance

200 response
{
  "$ref": "#/components/schemas/CreditBalance"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$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

CreditPolicy

200 response
{
  "$ref": "#/components/schemas/CreditPolicy"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$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
Schema
{
  "type": "string",
  "maxLength": 512
}

limit · query · optional

Schema
Schema
{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 50
}

type · query · optional

Schema

CreditEntryType

Schema
{
  "$ref": "#/components/schemas/CreditEntryType"
}

Responses

200 Ledger entries

200 response · application/json

CreditTransaction · Page

200 response
{
  "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

Problem

401 response
{
  "$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

TrialCreditState

200 response
{
  "$ref": "#/components/schemas/TrialCreditState"
}

401 Authentication required or invalid

Headers: Cache-Control, X-Request-Id

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected internal error occurred

Headers: Cache-Control, X-Request-Id

500 response · application/problem+json

Problem

500 response
{
  "$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

Problem

503 response
{
  "$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
Schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255
}

Request body · optional

Schema · application/json
Schema
{
  "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

TrialCreditState

201 response
{
  "$ref": "#/components/schemas/TrialCreditState"
}

401 Authentication required or invalid

Headers: Cache-Control, X-Request-Id

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

403 Authenticated but not permitted, or CSRF validation failed

Headers: Cache-Control, X-Request-Id

403 response · application/problem+json

Problem

403 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

Headers: Cache-Control, X-Request-Id

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

Headers: Cache-Control, X-Request-Id

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

500 An unexpected internal error occurred

Headers: Cache-Control, X-Request-Id

500 response · application/problem+json

Problem

500 response
{
  "$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

Problem

503 response
{
  "$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

DeliveryWebhook

200 response
{
  "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

Problem

401 response
{
  "$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

CreateDeliveryWebhookRequest

Schema
{
  "$ref": "#/components/schemas/CreateDeliveryWebhookRequest"
}

Responses

201 Created

201 response · application/json

DeliveryWebhook

201 response
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "webhook"
  ],
  "properties": {
    "webhook": {
      "$ref": "#/components/schemas/DeliveryWebhook"
    }
  }
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^cbk_[A-Za-z0-9_-]{8,}$"
}

Responses

204 Removed

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$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
Schema
{
  "type": "string",
  "pattern": "^cbk_[A-Za-z0-9_-]{8,}$"
}

Responses

200 Test attempted

200 response · application/json

DeliveryWebhook

200 response
{
  "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

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$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
Schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 512
}

limit · query · optional

Schema
Schema
{
  "type": "integer",
  "minimum": 1,
  "maximum": 50
}

source · query · optional

Schema
Schema
{
  "type": "string",
  "pattern": "^(google|youtube|google_[a-z]+|youtube_[a-z_]+)$"
}

status · query · optional

Schema
Schema
{
  "type": "string",
  "enum": [
    "completed",
    "failed",
    "pending",
    "processing"
  ]
}

mode · query · optional

Schema
Schema
{
  "type": "string",
  "enum": [
    "async",
    "batch",
    "realtime"
  ]
}

from · query · optional

Schema
Schema
{
  "type": "string",
  "format": "date-time"
}

to · query · optional

Schema
Schema
{
  "type": "string",
  "format": "date-time"
}

Responses

200 Job page

200 response · application/json

ConsoleJob · Pagination

200 response
{
  "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

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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
Schema
{
  "type": "string"
}

jobId · path · required

Schema
Schema
{
  "type": "string",
  "pattern": "^job_[A-Za-z0-9_-]+$"
}

Responses

200 Job detail

200 response · application/json

ConsoleJob

200 response
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/ConsoleJob"
    }
  }
}
200 response · text/plain
200 response
{
  "type": "string"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

406 Neither application/json nor text/plain is acceptable; response is JSON

406 response · application/json

QueryRepresentationError

406 response
{
  "$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
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
Schema
{
  "type": "string"
}

jobId · path · required

Schema
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

MarkdownQueryResult

200 response
{
  "anyOf": [
    {
      "$ref": "#/components/schemas/MarkdownQueryResult"
    },
    {
      "type": "object",
      "additionalProperties": true
    }
  ]
}
200 response · text/plain
200 response
{
  "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

QueryRepresentationError

400 response
{
  "$ref": "#/components/schemas/QueryRepresentationError"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

406 Neither application/json nor text/plain is acceptable; response is JSON

406 response · application/json

QueryRepresentationError

406 response
{
  "$ref": "#/components/schemas/QueryRepresentationError"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 Result expired

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

422 The job failed. The response includes the saved failure reason in detail when available.

422 response · application/problem+json

Problem

422 response
{
  "$ref": "#/components/schemas/Problem"
}

503 A required dependency or catalog is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$ref": "#/components/schemas/Problem"
}

Bulk processing API

Bulk endpoints have a dedicated reference with parameters, request examples and response schemas. Open Bulk processing API

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
Schema
{
  "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
200 response
{
  "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

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

422 Request validation failed

422 response · application/problem+json

Problem

422 response
{
  "$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
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
200 response
{
  "type": "string",
  "format": "binary"
}

401 Authentication required or invalid

401 response · application/problem+json

Problem

401 response
{
  "$ref": "#/components/schemas/Problem"
}

404 Resource not found or not owned by the caller

404 response · application/problem+json

Problem

404 response
{
  "$ref": "#/components/schemas/Problem"
}

409 Resource state or idempotency conflict

409 response · application/problem+json

Problem

409 response
{
  "$ref": "#/components/schemas/Problem"
}

410 The temporary artifact has expired

410 response · application/problem+json

Problem

410 response
{
  "$ref": "#/components/schemas/Problem"
}

503 A required dependency or catalog is temporarily unavailable

503 response · application/problem+json

Problem

503 response
{
  "$ref": "#/components/schemas/Problem"
}

Schema definitions

APIKeyIdentity
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
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
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
AgentApproval
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "allowAccountBalance": {
      "const": true
    }
  },
  "required": [
    "scopes",
    "allowAccountBalance"
  ]
}
AgentBrowserClaim
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
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
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
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
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
AgentConnectionResponse
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "connection": {
      "$ref": "#/components/schemas/AgentConnection"
    }
  },
  "required": [
    "connection"
  ]
}
AgentHandoff
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
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
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
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
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
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
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
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
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
ApiAccessPlan
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "billingMode": {
      "type": "string"
    },
    "status": {
      "type": "string"
    }
  }
}
ApiAccessPricing
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
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
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
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
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
BillingPaymentPage
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BillingPayment"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}
BillingPayment
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
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
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
BulkJobPage
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BulkJob"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}
BulkJobResponse
BulkJobResponse
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/BulkJob"
    }
  }
}
ConsoleJob
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
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
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
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
CreateDeliveryWebhookRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "url"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string",
      "format": "uri"
    }
  }
}
CreditBalance
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
CreditEntryType
{
  "type": "string",
  "enum": [
    "subscription_grant",
    "topup_grant",
    "payment_reversal",
    "admin_adjustment",
    "trial_grant"
  ]
}
CreditPolicy
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
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
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
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
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
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
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"
    }
  }
}
LegalAcceptanceRequest
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
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
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
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
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
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
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
Page
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {}
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}
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
Password
{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "writeOnly": true
}
PlanCatalog
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
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
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
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
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
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
FieldError
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "field",
    "code",
    "message"
  ],
  "properties": {
    "field": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
PublicLegalVersions
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
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
PublicStatusComponent
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "name",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "operational",
        "degraded",
        "outage"
      ]
    }
  }
}
PublicTrialOffer
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
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
Reauthentication
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "reauthenticatedUntil"
  ],
  "properties": {
    "reauthenticatedUntil": {
      "type": "string",
      "format": "date-time"
    }
  }
}
RegisterRequest
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
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
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
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
SubscriptionCancellationChange
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "cancelAtPeriodEnd",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^sub_"
    },
    "cancelAtPeriodEnd": {
      "type": "boolean"
    },
    "status": {
      "type": "string",
      "enum": [
        "submitted"
      ]
    }
  }
}
SubscriptionChange
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
TokenRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "token"
  ],
  "properties": {
    "token": {
      "type": "string",
      "minLength": 32,
      "maxLength": 256,
      "writeOnly": true
    }
  }
}
TrialCreditState
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
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
TrialCreditRequestStatus
{
  "type": "string",
  "enum": [
    "pending",
    "approved",
    "rejected"
  ]
}
UpdateAccountRequest
UpdateAccountRequest
{
  "type": "object",
  "additionalProperties": false,
  "minProperties": 1,
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "timezone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    }
  }
}
UpdateBulkJobRequest
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
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
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."
    }
  }
}