FlashData API V2
API reference
The stable V2 HTTP surface. Every failure uses an application/problem+json body with a request ID.
Authentication
cookieSessionapiKey / cookie / __Host-fd_session
Opaque Web session. The browser cannot read this cookie.
csrfTokenapiKey / header / X-CSRF-Token
apiKeyapiKey / header / X-API-Key
System
2GET/healthService health
- Operation ID
getHealth- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Healthy
GET/statusRead the public component status summary
- Operation ID
getPublicStatus- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Public status summary
Cache-Control
Auth
14POST/auth/registerCreate a pending FlashData account
The submitted Terms and Privacy versions must match the current published legal bundle.
- Operation ID
register- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredResponses
201Account created; email verification required
Cache-Control / X-Request-Id
409Resource state or idempotency conflict
422Request validation failed
429Rate, concurrency, batch, or pending-job limit exceeded
Retry-After
500An unexpected internal error occurred
503A required dependency or catalog is temporarily unavailable
POST/auth/loginCreate an opaque Web session
Sets the Secure, HttpOnly `__Host-fd_session` cookie. 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.
- Operation ID
login- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredResponses
200Authenticated
Set-Cookie / Cache-Control / X-Request-Id
401Authentication required or invalid
403Login is forbidden; Problem.code is email_not_verified, account_suspended, account_deletion_processing, account_deletion_failed, or account_deleted
422Request validation failed
423Account temporarily locked
Retry-After
429Rate, concurrency, batch, or pending-job limit exceeded
Retry-After
POST/auth/logoutRevoke the current session
- Operation ID
logout- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
204Session revoked and cookie cleared
Set-Cookie / Cache-Control / X-Request-Id
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
GET/auth/meRead the current account and user
- Operation ID
getCurrentAccount- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
GET/auth/csrfGet the CSRF token bound to the current session
- Operation ID
getCsrfToken- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200CSRF token
Cache-Control / X-Request-Id
Schema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"csrfToken"
],
"properties": {
"csrfToken": {
"type": "string",
"minLength": 32,
"readOnly": true
}
}
}401Authentication required or invalid
POST/auth/email-verificationsRequest 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.
- Operation ID
requestEmailVerification- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredSchema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 320
}
}
}Responses
202Request accepted. The response does not reveal whether an account exists.
Cache-Control / X-Request-Id
Schema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"accepted"
],
"properties": {
"accepted": {
"type": "boolean",
"const": true
}
}
}422Anonymous authentication request validation failed
Cache-Control / X-Request-Id
429Anonymous authentication rate limit exceeded
Cache-Control / Retry-After / X-Request-Id
500An unexpected anonymous authentication error occurred
Cache-Control / X-Request-Id
503An anonymous authentication dependency is temporarily unavailable
Cache-Control / X-Request-Id
POST/auth/email-verifications/confirmVerify an email and activate the account
Atomically consumes the one-time token, activates the Account and User, and grants the entitlement snapshot's trial microcredits once with idempotency key `trial:{accountId}`. It does not create a Session; the user must log in explicitly.
- Operation ID
confirmEmailVerification- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredResponses
200Account activated
Cache-Control / X-Request-Id
Schema / application/json
{
"allOf": [
{
"$ref": "#/components/schemas/Account"
},
{
"type": "object",
"properties": {
"status": {
"const": "active"
},
"emailVerified": {
"const": true
}
}
}
]
}410One-time token is invalid, expired, invalidated, already used, or lost a concurrent confirmation race. Problem.code is `token_unavailable`.
Cache-Control / X-Request-Id
422Anonymous authentication request validation failed
Cache-Control / X-Request-Id
429Anonymous authentication rate limit exceeded
Cache-Control / Retry-After / X-Request-Id
500An unexpected anonymous authentication error occurred
Cache-Control / X-Request-Id
503An anonymous authentication dependency is temporarily unavailable
Cache-Control / X-Request-Id
POST/auth/password-resetsRequest 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.
- Operation ID
requestPasswordReset- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredSchema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 320
}
}
}Responses
202Request accepted. The response does not reveal whether an account exists.
Cache-Control / X-Request-Id
Schema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"accepted"
],
"properties": {
"accepted": {
"type": "boolean",
"const": true
}
}
}422Anonymous authentication request validation failed
Cache-Control / X-Request-Id
429Anonymous authentication rate limit exceeded
Cache-Control / Retry-After / X-Request-Id
500An unexpected anonymous authentication error occurred
Cache-Control / X-Request-Id
503An anonymous authentication dependency is temporarily unavailable
Cache-Control / X-Request-Id
POST/auth/password-resets/confirmSet 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.
- Operation ID
confirmPasswordReset- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredSchema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"token",
"password"
],
"properties": {
"token": {
"type": "string",
"minLength": 32,
"maxLength": 256,
"writeOnly": true
},
"password": {
"$ref": "#/components/schemas/Password"
}
}
}Responses
204Password updated; existing sessions revoked
Cache-Control / X-Request-Id
410One-time token is invalid, expired, invalidated, already used, or lost a concurrent confirmation race. Problem.code is `token_unavailable`.
Cache-Control / X-Request-Id
422Anonymous authentication request validation failed
Cache-Control / X-Request-Id
429Anonymous authentication rate limit exceeded
Cache-Control / Retry-After / X-Request-Id
500An unexpected anonymous authentication error occurred
Cache-Control / X-Request-Id
503An anonymous authentication dependency is temporarily unavailable
Cache-Control / X-Request-Id
GET/auth/sessionsList active sessions for the current user
- Operation ID
listSessions- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Sessions
Cache-Control / X-Request-Id
Schema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Session"
}
}
}
}401Authentication required or invalid
DELETE/auth/sessionsRevoke all sessions except the current one
- Operation ID
revokeOtherSessions- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
204Other sessions revoked
Cache-Control / X-Request-Id
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
DELETE/auth/sessions/{sessionId}Revoke one session
- Operation ID
revokeSession- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
sessionIdpathRequiredSchema
{
"type": "string",
"pattern": "^ses_"
}Responses
204Session revoked. If it was the current Session, the cookie is cleared.
Set-Cookie / Cache-Control / X-Request-Id
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
422Request validation failed
503A required dependency or catalog is temporarily unavailable
POST/auth/re-authenticateVerify the current password for a sensitive operation
Records a short-lived recent-auth proof on the current server-side session.
- Operation ID
reauthenticateSession- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredSchema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"password"
],
"properties": {
"password": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"writeOnly": true
}
}
}Responses
200Session has recent authentication
Cache-Control / X-Request-Id
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
429Rate, concurrency, batch, or pending-job limit exceeded
Retry-After
PATCH/auth/passwordChange the password and rotate the current session
- Operation ID
changePassword- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredSchema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"currentPassword",
"newPassword"
],
"properties": {
"currentPassword": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"writeOnly": true
},
"newPassword": {
"$ref": "#/components/schemas/Password"
},
"revokeOtherSessions": {
"type": "boolean",
"default": true
}
}
}Responses
204Password changed; current session rotated and other sessions revoked when requested
Set-Cookie / Cache-Control / X-Request-Id
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
422Request validation failed
Account
6GET/accountRead account settings
- Operation ID
getAccount- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
PATCH/accountUpdate profile settings
- Operation ID
updateAccount- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredSchema / application/json
{
"$ref": "#/components/schemas/UpdateAccountRequest"
}Responses
200Updated account
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
422Request validation failed
DELETE/accountSchedule account deletion and revoke all existing sessions and API Keys
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.
- Operation ID
deleteAccount- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredSchema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"password",
"confirmation"
],
"properties": {
"password": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"writeOnly": true
},
"confirmation": {
"type": "string",
"const": "DELETE"
}
}
}Responses
202Deletion scheduled; active sessions and keys revoked
Schema / application/json
{
"$ref": "#/components/schemas/AccountDeletionRequest"
}401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
422Request validation failed
GET/account/deletionRead the current account deletion request
- Operation ID
getAccountDeletion- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Current deletion request
Schema / application/json
{
"$ref": "#/components/schemas/AccountDeletionRequest"
}401Authentication required or invalid
404Resource not found or not owned by the caller
DELETE/account/deletionCancel 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.
- Operation ID
cancelAccountDeletion- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
204Deletion cancelled, account reactivated, and recovery Session rotated according to the legal-acceptance gate
Set-Cookie / Cache-Control / X-Request-Id
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
POST/account/legal-acceptancesAccept 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.
- Operation ID
acceptCurrentLegalTerms- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredSchema / application/json
{
"$ref": "#/components/schemas/LegalAcceptanceRequest"
}Responses
200Legal acceptance recorded and Session rotated to full mode
Set-Cookie / Cache-Control / X-Request-Id
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
422Request validation failed
Onboarding
2GET/onboardingRead resumable onboarding progress
- Operation ID
getOnboardingProgress- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Current onboarding state
Cache-Control / X-Request-Id
401Authentication required or invalid
Cache-Control / X-Request-Id
500An unexpected internal error occurred
Cache-Control / X-Request-Id
503A required dependency or onboarding record is temporarily unavailable
Cache-Control / X-Request-Id
PATCH/onboardingAdvance onboarding without allowing progress to move backward
- Operation ID
updateOnboardingProgress- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Request body
RequiredSchema / application/json
{
"$ref": "#/components/schemas/UpdateOnboardingRequest"
}Responses
200Updated onboarding state
Cache-Control / X-Request-Id
401Authentication required or invalid
Cache-Control / X-Request-Id
403Authenticated but not permitted, or CSRF validation failed
Cache-Control / X-Request-Id
409Resource state or idempotency conflict
Cache-Control / X-Request-Id
422Request validation failed
Cache-Control / X-Request-Id
500An unexpected internal error occurred
Cache-Control / X-Request-Id
503A required dependency or onboarding record is temporarily unavailable
Cache-Control / X-Request-Id
Overview
1GET/overviewRead the account dashboard aggregate
- Operation ID
getConsoleOverview- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Account-scoped overview
Cache-Control / X-Request-Id
401Authentication required or invalid
Cache-Control / X-Request-Id
500An unexpected internal error occurred
Cache-Control / X-Request-Id
503A required dependency or onboarding record is temporarily unavailable
Cache-Control / X-Request-Id
Playground
3POST/playground/queries/realtimeExecute a synchronous query from the authenticated Web console
The browser submits an owned API Key public ID, never its plaintext secret. The server verifies that the Key is active and grants queries:write before invoking the same query application service as the Data API.
- Operation ID
executeConsoleRealtimeQuery- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredResponses
200Completed query
Cache-Control / X-Request-Id
Schema / application/json
{
"$ref": "#/components/schemas/RealtimeQueryResponse"
}401Authentication required or invalid
Cache-Control / X-Request-Id
402Account has insufficient available credits
403Authenticated but not permitted, or CSRF validation failed
Cache-Control / X-Request-Id
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
Cache-Control / X-Request-Id
422Request validation failed
Cache-Control / X-Request-Id
429Rate, concurrency, batch, or pending-job limit exceeded
Retry-After
502An upstream provider failed
503A required dependency or onboarding record is temporarily unavailable
Cache-Control / X-Request-Id
504An upstream provider timed out
POST/playground/queriesSubmit a durable asynchronous query from the authenticated Web console
The selected API Key is referenced by public ID for attribution and scope enforcement; its plaintext secret is never loaded by the Web console.
- Operation ID
createConsoleAsyncQuery- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredResponses
202Job accepted
Cache-Control / X-Request-Id / Location
401Authentication required or invalid
Cache-Control / X-Request-Id
402Account has insufficient available credits
403Authenticated but not permitted, or CSRF validation failed
Cache-Control / X-Request-Id
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
Cache-Control / X-Request-Id
422Request validation failed
Cache-Control / X-Request-Id
429Rate, concurrency, batch, or pending-job limit exceeded
Retry-After
503A required dependency or onboarding record is temporarily unavailable
Cache-Control / X-Request-Id
POST/playground/queries/batchAtomically validate and submit a Web console query batch
All items are validated before one reservation. Any validation, reservation, or submission failure rejects the entire batch; execution-time Job failures remain independently visible after acceptance.
- Operation ID
createConsoleBatchQueries- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredSchema / application/json
{
"$ref": "#/components/schemas/ConsoleBatchQueryRequest"
}Responses
202Batch accepted
Cache-Control / X-Request-Id
401Authentication required or invalid
Cache-Control / X-Request-Id
402Account has insufficient available credits
403Authenticated but not permitted, or CSRF validation failed
Cache-Control / X-Request-Id
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
Cache-Control / X-Request-Id
422Request validation failed
Cache-Control / X-Request-Id
429Rate, concurrency, batch, or pending-job limit exceeded
Retry-After
503A required dependency or onboarding record is temporarily unavailable
Cache-Control / X-Request-Id
API Keys
4GET/api-keysList API Key metadata
- Operation ID
listApiKeys- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200API Keys without secrets
Schema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiKey"
}
}
}
}401Authentication required or invalid
POST/api-keysCreate an API Key and reveal its secret once
- Operation ID
createApiKey- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredResponses
201Created; the same idempotent replay may return the same encrypted response for five minutes
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
409Resource state or idempotency conflict
422Request validation failed
503A required dependency or catalog is temporarily unavailable
DELETE/api-keys/{keyId}Revoke an API Key
- Operation ID
revokeApiKey- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
keyIdpathRequiredSchema
{
"type": "string",
"pattern": "^key_"
}Responses
204Revoked
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
503A required dependency or catalog is temporarily unavailable
POST/api-keys/{keyId}/rotateCreate a replacement key and schedule old-key revocation
The old key remains active during a bounded overlap window. Omitting `revokeOldAt` uses a 24-hour overlap, capped by the old key expiry. An explicit value must be in the future, no more than seven days from the request, and no later than the old key expiry. Internal primary and retiring rotation states are not exposed as public API Key statuses.
- Operation ID
rotateApiKey- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
keyIdpathRequiredSchema
{
"type": "string",
"pattern": "^key_"
}Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
OptionalSchema / application/json
{
"type": "object",
"additionalProperties": false,
"properties": {
"revokeOldAt": {
"type": "string",
"format": "date-time",
"description": "Optional old-key revocation time; defaults to 24 hours and cannot exceed seven days or the old key expiry."
}
}
}Responses
201Replacement created; secret returned once
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
422Request validation failed
503A required dependency or catalog is temporarily unavailable
Catalog
3GET/catalog/sourcesList public source capabilities without account-specific pricing
- Operation ID
listPublicDataSources- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Public source catalog
Cache-Control
Schema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DataSource"
}
}
}
}GET/plansList public USD plans and prices
- Operation ID
listPlans- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Public plan catalog
Cache-Control
GET/legal/currentRead the current Terms and Privacy versions required for signup
- Operation ID
getCurrentLegalVersions- Security
- Public
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Current legal version catalog
Cache-Control
Billing
5GET/billing/subscriptionRead the effective Stripe subscription
- Operation ID
getSubscription- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Subscription or PAYG entitlement
401Authentication required or invalid
POST/billing/checkout-sessionsCreate a Stripe-hosted Checkout Session
The server verifies that the FlashData price is active, available in the current livemode, USD-denominated, and matches purchaseType. Product, provider price, currency, success URL and cancel URL are never accepted from the browser.
- Operation ID
createCheckoutSession- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredSchema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"priceId"
],
"properties": {
"priceId": {
"type": "string",
"pattern": "^prc_"
},
"purchaseType": {
"type": "string",
"enum": [
"subscription",
"top_up"
],
"default": "subscription"
}
}
}Responses
201Stripe Checkout Session
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
409Resource state or idempotency conflict
422Request validation failed
502An upstream provider failed
503The billing catalog or provider is not configured or is temporarily unavailable
POST/billing/portal-sessionsCreate a Stripe Customer Portal Session
- Operation ID
createBillingPortalSession- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Responses
201Stripe Customer Portal Session
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
502An upstream provider failed
503The billing catalog or provider is not configured or is temporarily unavailable
GET/billing/invoicesList Stripe invoice projections
- Operation ID
listInvoices- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
cursorqueryOptionalSchema
{
"type": "string",
"maxLength": 512
}limitqueryOptionalSchema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}Responses
200Invoices
401Authentication required or invalid
GET/billing/paymentsList account-scoped top-up and refund payment projections
- Operation ID
listBillingPayments- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
cursorqueryOptionalSchema
{
"type": "string",
"maxLength": 512
}limitqueryOptionalSchema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}Responses
200One-time payment history without provider secrets
401Authentication required or invalid
Credits
3GET/credits/balanceRead current available and reserved credits
- Operation ID
getCreditBalance- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Credit balance
401Authentication required or invalid
GET/credits/policyRead the effective account credit grant and charging policy
- Operation ID
getCreditPolicy- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Effective credit policy
401Authentication required or invalid
GET/credits/transactionsList credit ledger entries
- Operation ID
listCreditTransactions- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
cursorqueryOptionalSchema
{
"type": "string",
"maxLength": 512
}limitqueryOptionalSchema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}typequeryOptionalResponses
200Ledger entries
Schema / application/json
{
"allOf": [
{
"$ref": "#/components/schemas/Page"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreditTransaction"
}
}
}
}
]
}401Authentication required or invalid
Usage
3GET/usage/summaryAggregate usage by source or day
- Operation ID
getUsageSummary- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
fromqueryRequiredInclusive range start. Usage ranges cannot exceed 366 days.
Schema
{
"type": "string",
"format": "date-time"
}toqueryRequiredExclusive range end. Usage ranges cannot exceed 366 days.
Schema
{
"type": "string",
"format": "date-time"
}groupByqueryOptionalSchema
{
"type": "string",
"enum": [
"day",
"source"
],
"default": "day"
}Responses
200Usage summary
401Authentication required or invalid
422Request validation failed
GET/usage/eventsList account-scoped request and job usage
- Operation ID
listUsageEvents- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
cursorqueryOptionalSchema
{
"type": "string",
"maxLength": 512
}limitqueryOptionalSchema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}fromqueryRequiredInclusive range start. Usage ranges cannot exceed 366 days.
Schema
{
"type": "string",
"format": "date-time"
}toqueryRequiredExclusive range end. Usage ranges cannot exceed 366 days.
Schema
{
"type": "string",
"format": "date-time"
}sourcequeryOptionalSchema
{
"type": "string"
}statusqueryOptionalSchema
{
"type": "string",
"enum": [
"accepted",
"processing",
"completed",
"failed",
"cancelled"
]
}Responses
200Usage events
Schema / application/json
{
"allOf": [
{
"$ref": "#/components/schemas/Page"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UsageEvent"
}
}
}
}
]
}401Authentication required or invalid
422Request validation failed
GET/usage/exportExport account usage as a streamed CSV file
- Operation ID
exportUsageCsv- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
fromqueryRequiredInclusive range start. Usage ranges cannot exceed 366 days.
Schema
{
"type": "string",
"format": "date-time"
}toqueryRequiredExclusive range end. Usage ranges cannot exceed 366 days.
Schema
{
"type": "string",
"format": "date-time"
}sourcequeryOptionalSchema
{
"type": "string"
}Responses
200UTF-8 CSV with a header row
Content-Disposition
Schema / text/csv
{
"type": "string"
}401Authentication required or invalid
422Request validation failed
Jobs
5GET/jobsList account jobs for the Web console
- Operation ID
listJobsForConsole- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
cursorqueryOptionalSchema
{
"type": "string",
"maxLength": 512
}limitqueryOptionalSchema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}statusqueryOptionalsourcequeryOptionalSchema
{
"type": "string"
}Responses
200Jobs
401Authentication required or invalid
GET/jobs/{jobId}Read one account job for the Web console
- Operation ID
getJobForConsole- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
jobIdpathRequiredSchema
{
"type": "string",
"pattern": "^job_"
}Responses
200Job
401Authentication required or invalid
404Resource not found or not owned by the caller
DELETE/jobs/{jobId}Cancel an account job that has not reached a terminal state
- Operation ID
cancelJobForConsole- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
jobIdpathRequiredSchema
{
"type": "string",
"pattern": "^job_"
}Responses
204Job cancelled and unused reservation released
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
GET/jobs/{jobId}/resultsRead a completed job result page for the Web console
- Operation ID
getJobResultsForConsole- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
jobIdpathRequiredSchema
{
"type": "string",
"pattern": "^job_"
}cursorqueryOptionalSchema
{
"type": "string",
"maxLength": 512
}limitqueryOptionalSchema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}Responses
200Result page
401Authentication required or invalid
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
POST/jobs/{jobId}/retryCreate a new job from a retryable failed job
- Operation ID
retryJobForConsole- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
jobIdpathRequiredSchema
{
"type": "string",
"pattern": "^job_"
}Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredSchema / application/json
{
"$ref": "#/components/schemas/ConsoleJobRetryRequest"
}Responses
202Replacement job accepted
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
422Request validation failed
429Rate, concurrency, batch, or pending-job limit exceeded
Retry-After
503A required dependency or catalog is temporarily unavailable
Storage Destinations
5GET/storage-destinationsList safe storage destination metadata
Disabled/soft-deleted destinations are excluded. Credentials are never projected.
- Operation ID
listStorageDestinations- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Destinations without credentials
Schema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorageDestination"
}
}
}
}401Authentication required or invalid
POST/storage-destinationsSave an encrypted customer storage destination
The destination starts in `invalid` state and becomes `active` only after a successful connection test. A soft-deleted name remains reserved.
- Operation ID
createStorageDestination- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredSchema / application/json
{
"$ref": "#/components/schemas/CreateStorageDestinationRequest"
}Responses
201Destination created
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
409Resource state or idempotency conflict
422Request validation failed
PATCH/storage-destinations/{destinationId}Update a destination or replace its credentials
Desired-state update uses `expectedVersion` for aggregate CAS. Credentials are optional unless the provider changes. Connection-affecting changes return the destination to `invalid` until retested.
- Operation ID
updateStorageDestination- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
destinationIdpathRequiredSchema
{
"type": "string",
"pattern": "^dst_"
}Request body
RequiredSchema / application/json
{
"$ref": "#/components/schemas/UpdateStorageDestinationRequest"
}Responses
200Updated destination
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
422Request validation failed
DELETE/storage-destinations/{destinationId}Disable and soft-delete a destination
Repeated deletion of the same owned destination is a no-op and returns 204. Deletion returns 409 while a pending or processing Job references the destination snapshot; successful deletion destroys the encrypted credential payload.
- Operation ID
deleteStorageDestination- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
destinationIdpathRequiredSchema
{
"type": "string",
"pattern": "^dst_"
}Responses
204Destination deleted
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
POST/storage-destinations/{destinationId}/testTest destination credentials without returning secrets
A connection test may execute more than once; it has no billing effect and only advances the latest test projection.
- Operation ID
testStorageDestination- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
destinationIdpathRequiredSchema
{
"type": "string",
"pattern": "^dst_"
}Responses
200Connection test result
Schema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"ok",
"latencyMs",
"testedAt"
],
"properties": {
"ok": {
"type": "boolean"
},
"latencyMs": {
"type": "integer",
"minimum": 0
},
"testedAt": {
"type": "string",
"format": "date-time"
}
}
}401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
502An upstream provider failed
Webhook Endpoints
9GET/webhook-endpointsList customer webhook endpoint metadata
- Operation ID
listWebhookEndpoints- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Responses
200Webhook endpoints
Schema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEndpoint"
}
}
}
}401Authentication required or invalid
POST/webhook-endpointsCreate and verify a customer webhook endpoint
- Operation ID
createWebhookEndpoint- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredSchema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"url",
"events"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"pattern": "^https://",
"description": "Public HTTPS origin only; credentials, paths, query strings, and fragments are rejected."
},
"events": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/OutboundWebhookEventType"
}
}
}
}Responses
201Endpoint created; signing secret returned once
Schema / application/json
{
"$ref": "#/components/schemas/WebhookEndpointCreated"
}401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
409Resource state or idempotency conflict
422Request validation failed
PATCH/webhook-endpoints/{endpointId}Update subscriptions or enable/disable an endpoint
Desired-state update is naturally idempotent by endpoint ID and aggregate version.
- Operation ID
updateWebhookEndpoint- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
endpointIdpathRequiredSchema
{
"type": "string",
"pattern": "^whe_"
}Request body
RequiredSchema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"expectedVersion"
],
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 0
},
"status": {
"type": "string",
"enum": [
"active",
"disabled"
]
},
"events": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/OutboundWebhookEventType"
}
}
}
}Responses
200Updated endpoint
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
DELETE/webhook-endpoints/{endpointId}Delete a customer webhook endpoint
Repeated deletion of the same owned endpoint is a no-op and returns 204.
- Operation ID
deleteWebhookEndpoint- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
endpointIdpathRequiredSchema
{
"type": "string",
"pattern": "^whe_"
}Responses
204Endpoint deleted
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
POST/webhook-endpoints/{endpointId}/rotate-secretRotate a customer webhook signing secret
- Operation ID
rotateWebhookSecret- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
endpointIdpathRequiredSchema
{
"type": "string",
"pattern": "^whe_"
}Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Responses
201New secret returned once
Schema / application/json
{
"$ref": "#/components/schemas/OneTimeSigningSecret"
}401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
409Resource state or idempotency conflict
POST/webhook-endpoints/{endpointId}/testRevalidate the endpoint target and enqueue a signed test delivery
- Operation ID
testWebhookEndpoint- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
endpointIdpathRequiredSchema
{
"type": "string",
"pattern": "^whe_"
}Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Responses
202Test delivery accepted after SSRF and DNS validation
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
422Request validation failed
GET/webhook-deliveriesList customer webhook delivery attempts
- Operation ID
listWebhookDeliveries- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
cursorqueryOptionalSchema
{
"type": "string",
"maxLength": 512
}limitqueryOptionalSchema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}endpointIdqueryOptionalSchema
{
"type": "string",
"pattern": "^whe_"
}Responses
200Delivery attempts
Schema / application/json
{
"allOf": [
{
"$ref": "#/components/schemas/Page"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookDelivery"
}
}
}
}
]
}401Authentication required or invalid
GET/webhook-deliveries/{deliveryId}Read one safe delivery timeline
- Operation ID
getWebhookDelivery- Security
- cookieSession
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
deliveryIdpathRequiredSchema
{
"type": "string",
"pattern": "^whd_"
}Responses
200Delivery metadata and attempts
Schema / application/json
{
"$ref": "#/components/schemas/WebhookDeliveryDetail"
}401Authentication required or invalid
404Resource not found or not owned by the caller
POST/webhook-deliveries/{deliveryId}/retryRetry an eligible dead-letter delivery
Reserves the next absolute attempt for the latest dead-letter delivery and starts a new bounded automatic retry window. A failed attempt with `nextAttemptAt` is still owned by the existing automatic retry command and cannot be retried manually. The event/endpoint lifecycle is capped at 1000 attempts; concurrent reservations return `409`.
- Operation ID
retryWebhookDelivery- Security
- cookieSession + csrfToken
- Server
https://api.flashdata.dev/v2http://localhost:5000/v2
Parameters
deliveryIdpathRequiredSchema
{
"type": "string",
"pattern": "^whd_"
}Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Responses
202Retry attempt scheduled
401Authentication required or invalid
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
Data Sources
1GET/sourcesList currently executable source modes and baseline cost estimates
`modes` 只包含当前部署具有真实 adapter/consumer 的模式；后续可靠 consumer 上线时通过 registry 扩展。`estimatedMicrocredits` 是提交前基线估算，最终收费 仍由账户 entitlement 与 reservation 结果决定。
- Operation ID
listDataSources- Security
- apiKey
- Server
https://data.flashdata.dev/v2http://localhost:5000/v2
Responses
200Sources
Cache-Control / X-Request-Id
Schema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DataSource"
}
}
}
}401API Key is missing, invalid, expired, or revoked
403Authenticated but not permitted, or CSRF validation failed
503A required dependency or catalog is temporarily unavailable
Queries
6POST/queries/realtimeExecute a synchronous query
- Operation ID
executeRealtimeQuery- Security
- apiKey
- Server
https://data.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredResponses
200Completed query
Cache-Control / X-Request-Id
Schema / application/json
{
"$ref": "#/components/schemas/RealtimeQueryResponse"
}401API Key is missing, invalid, expired, or revoked
402Account has insufficient available credits
403Authenticated but not permitted, or CSRF validation failed
409Resource state or idempotency conflict
422Request validation failed
429Rate, concurrency, batch, or pending-job limit exceeded
Retry-After
502An upstream provider failed
503A required dependency or catalog is temporarily unavailable
504An upstream provider timed out
POST/queriesSubmit a durable asynchronous query
- Operation ID
createAsyncQuery- Security
- apiKey
- Server
https://data.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredResponses
202Job accepted
Cache-Control / X-Request-Id / Location
401API Key is missing, invalid, expired, or revoked
402Account has insufficient available credits
403Authenticated but not permitted, or CSRF validation failed
409Resource state or idempotency conflict
422Request validation failed
429Rate, concurrency, batch, or pending-job limit exceeded
Retry-After
503A required dependency or catalog is temporarily unavailable
POST/queries/batchAtomically validate and submit a batch of queries
全部 query 先完成 schema/mode 校验，再原子预留整批额度并一次提交。 任一预校验、预留或提交失败时整批不接受；不存在部分 accepted 响应。
- Operation ID
createBatchQueries- Security
- apiKey
- Server
https://data.flashdata.dev/v2http://localhost:5000/v2
Parameters
Idempotency-KeyheaderRequiredSchema
{
"type": "string",
"minLength": 1,
"maxLength": 255
}Request body
RequiredSchema / application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"queries"
],
"properties": {
"queries": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"$ref": "#/components/schemas/QueryRequest"
}
}
}
}Responses
202Batch accepted
Cache-Control / X-Request-Id
401API Key is missing, invalid, expired, or revoked
402Account has insufficient available credits
403Authenticated but not permitted, or CSRF validation failed
409Resource state or idempotency conflict
422Request validation failed
429Rate, concurrency, batch, or pending-job limit exceeded
Retry-After
503A required dependency or catalog is temporarily unavailable
GET/queries/{jobId}Read an asynchronous query job
- Operation ID
getQueryJob- Security
- apiKey
- Server
https://data.flashdata.dev/v2http://localhost:5000/v2
Parameters
jobIdpathRequiredSchema
{
"type": "string",
"pattern": "^job_"
}Responses
200Job owned by the authenticated account
Cache-Control / X-Request-Id
401API Key is missing, invalid, expired, or revoked
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
503A required dependency or catalog is temporarily unavailable
DELETE/queries/{jobId}Cancel a job that has not reached a terminal state
取消使用 Job 状态机的自然幂等边界；重复取消已 cancelled Job 仍返回 204。 completed/failed 等不可取消终态返回 409，缺失和非本账户 Job 统一返回 404。
- Operation ID
cancelQueryJob- Security
- apiKey
- Server
https://data.flashdata.dev/v2http://localhost:5000/v2
Parameters
jobIdpathRequiredSchema
{
"type": "string",
"pattern": "^job_"
}Responses
204Job cancelled; unused reservation released
Cache-Control / X-Request-Id
401API Key is missing, invalid, expired, or revoked
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
503A required dependency or catalog is temporarily unavailable
GET/queries/{jobId}/resultsRead completed job results
pending/processing Job 返回 409 `query_job_not_completed`；failed/cancelled Job 没有可读取结果，同样返回该稳定冲突码。缺失和非本账户 Job 统一返回 404。
- Operation ID
getQueryJobResults- Security
- apiKey
- Server
https://data.flashdata.dev/v2http://localhost:5000/v2
Parameters
jobIdpathRequiredSchema
{
"type": "string",
"pattern": "^job_"
}cursorqueryOptionalSchema
{
"type": "string",
"maxLength": 512
}limitqueryOptionalSchema
{
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}Responses
200Result page
Cache-Control / X-Request-Id
401API Key is missing, invalid, expired, or revoked
403Authenticated but not permitted, or CSRF validation failed
404Resource not found or not owned by the caller
409Job has not completed
503A required dependency or catalog is temporarily unavailable
Schema catalog
Account
{
"type": "object",
"description": "Deleted accounts are only returned through authorized Admin projections; their identity fields are redacted.",
"additionalProperties": false,
"required": [
"id",
"name",
"email",
"status",
"emailVerified",
"legalAcceptanceRequired",
"role",
"timezone",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^acct_"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
],
"format": "email"
},
"status": {
"type": "string",
"enum": [
"pending_verification",
"active",
"suspended",
"deleting",
"deleted"
]
},
"emailVerified": {
"type": "boolean"
},
"legalAcceptanceRequired": {
"type": "boolean"
},
"role": {
"type": "string",
"enum": [
"user",
"admin"
]
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}AccountDeletionRequest
{
"type": "object",
"description": "User-safe deletion summary. Durable processor cursor and per-step metadata are internal operational state and are intentionally omitted.",
"additionalProperties": false,
"required": [
"id",
"status",
"requestedAt",
"scheduledFor",
"cancellable",
"billingCancellationStatus",
"activeJobsAtRequest",
"retryable"
],
"properties": {
"id": {
"type": "string",
"pattern": "^del_"
},
"status": {
"type": "string",
"enum": [
"scheduled",
"cancelled",
"processing",
"completed",
"failed"
]
},
"requestedAt": {
"type": "string",
"format": "date-time"
},
"scheduledFor": {
"type": "string",
"format": "date-time"
},
"cancellable": {
"type": "boolean"
},
"cancelledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"processingStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureCode": {
"type": [
"string",
"null"
],
"maxLength": 80
},
"billingCancellationStatus": {
"type": "string",
"enum": [
"not_required",
"pending",
"completed",
"failed"
]
},
"activeJobsAtRequest": {
"type": "integer",
"minimum": 0
},
"retryable": {
"type": "boolean",
"description": "True only when an Admin-audited processor retry is possible; it does not grant the user mutation access."
}
}
}ApiKey
{
"type": "object",
"description": "Public API Key metadata. Internal primary/retiring rotation state is intentionally omitted; a retiring key remains `active` until scheduledRevocationAt.",
"additionalProperties": false,
"required": [
"id",
"name",
"environment",
"prefix",
"last4",
"scopes",
"status",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^key_"
},
"name": {
"type": "string"
},
"environment": {
"type": "string",
"enum": [
"test",
"live"
]
},
"prefix": {
"type": "string"
},
"last4": {
"type": "string",
"minLength": 4,
"maxLength": 4
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"active",
"revoked",
"expired"
]
},
"lastUsedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledRevocationAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Planned revocation time for an overlapping retiring key; null for a primary or immediately revoked key."
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}ApiKeyCreated
{
"type": "object",
"additionalProperties": false,
"required": [
"apiKey",
"secret"
],
"properties": {
"apiKey": {
"$ref": "#/components/schemas/ApiKey"
},
"secret": {
"type": "string",
"readOnly": true,
"pattern": "^fd_(test|live)_",
"description": "Plaintext secret returned only by this create/rotate transaction. 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"
}
}
}BatchQueryResponse
{
"type": "object",
"additionalProperties": false,
"required": [
"batchId",
"jobs",
"totalEstimatedMicrocredits"
],
"properties": {
"batchId": {
"type": "string",
"pattern": "^batch_"
},
"jobs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Job"
}
},
"totalEstimatedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
}BillingPaymentPage
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BillingPayment"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
}BillingPayment
{
"description": "Account-scoped top-up projection. Refund state is updated only from verified provider events; this API does not initiate refunds.",
"type": "object",
"additionalProperties": false,
"required": [
"id",
"purchaseType",
"status",
"currency",
"amount",
"refundedAmount",
"creditsMicrocredits",
"reversedCreditsMicrocredits",
"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"
},
"creditsMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"reversedCreditsMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Cumulative credits removed by append-only payment_reversal entries; never exceeds creditsMicrocredits."
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}ConsoleBatchQueryRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"apiKeyId",
"queries"
],
"properties": {
"apiKeyId": {
"type": "string",
"pattern": "^key_[A-Za-z0-9_-]{8,}$",
"description": "Owned active API Key metadata selected for scope enforcement and usage attribution; never a plaintext API Key."
},
"queries": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"$ref": "#/components/schemas/QueryRequest"
}
}
}
}ConsoleJobRetryRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"apiKeyId"
],
"properties": {
"apiKeyId": {
"type": "string",
"pattern": "^key_[A-Za-z0-9_-]{8,}$",
"description": "Owned active API Key used for the replacement Job. The original Job's Key is never restored implicitly."
}
}
}ConsoleOverview
{
"type": "object",
"additionalProperties": false,
"required": [
"account",
"onboarding",
"subscription",
"balance",
"usage",
"recentJobs",
"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"
}
]
},
"usage": {
"oneOf": [
{
"$ref": "#/components/schemas/UsageSummary"
},
{
"type": "null"
}
]
},
"recentJobs": {
"type": "array",
"maxItems": 10,
"items": {
"$ref": "#/components/schemas/Job"
}
},
"publicStatus": {
"oneOf": [
{
"$ref": "#/components/schemas/PublicStatus"
},
{
"type": "null"
}
]
},
"degradedSections": {
"type": "array",
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"subscription",
"balance",
"usage",
"recent_jobs",
"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"
}
}
}ConsoleQueryRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"apiKeyId",
"query"
],
"properties": {
"apiKeyId": {
"type": "string",
"pattern": "^key_[A-Za-z0-9_-]{8,}$",
"description": "Owned active API Key metadata selected for scope enforcement and usage attribution; never a plaintext API Key."
},
"query": {
"$ref": "#/components/schemas/QueryRequest"
}
}
}CreateApiKeyRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"environment",
"scopes"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"environment": {
"type": "string",
"enum": [
"test",
"live"
]
},
"scopes": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"queries:read",
"queries:write",
"usage:read"
]
}
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}CreateStorageDestinationRequest
{
"oneOf": [
{
"$ref": "#/components/schemas/S3StorageDestinationWrite"
},
{
"$ref": "#/components/schemas/S3CompatibleStorageDestinationWrite"
},
{
"$ref": "#/components/schemas/GcsStorageDestinationWrite"
},
{
"$ref": "#/components/schemas/AzureStorageDestinationWrite"
},
{
"$ref": "#/components/schemas/BosStorageDestinationWrite"
},
{
"$ref": "#/components/schemas/OssStorageDestinationWrite"
},
{
"$ref": "#/components/schemas/TosStorageDestinationWrite"
}
]
}AzureStorageDestinationWrite
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"provider",
"config",
"credentials"
],
"properties": {
"name": {
"$ref": "#/components/schemas/StorageDestinationName"
},
"provider": {
"type": "string",
"const": "azure"
},
"config": {
"$ref": "#/components/schemas/AzureStorageConfig"
},
"credentials": {
"$ref": "#/components/schemas/AzureStorageCredentials",
"writeOnly": true
}
}
}AzureStorageConfig
{
"type": "object",
"additionalProperties": false,
"required": [
"accountUrl",
"container"
],
"properties": {
"accountUrl": {
"$ref": "#/components/schemas/PublicHttpsStorageEndpoint"
},
"container": {
"type": "string",
"minLength": 3,
"maxLength": 63,
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?!-))*[a-z0-9]$"
},
"objectPrefix": {
"$ref": "#/components/schemas/StorageObjectPrefix"
}
}
}AzureStorageCredentials
{
"oneOf": [
{
"type": "object",
"title": "Standard Azure connection string",
"additionalProperties": false,
"required": [
"connectionString"
],
"properties": {
"connectionString": {
"type": "string",
"minLength": 1,
"maxLength": 8192,
"description": "Standard public Azure connection string. Its derived or explicit BlobEndpoint must normalize to the accompanying config.accountUrl."
}
}
},
{
"type": "object",
"title": "Azure named key",
"additionalProperties": false,
"required": [
"accountName",
"accountKey"
],
"properties": {
"accountName": {
"type": "string",
"pattern": "^[a-z0-9]{3,24}$"
},
"accountKey": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
}
},
{
"type": "object",
"title": "Azure SAS token",
"additionalProperties": false,
"required": [
"sasToken"
],
"properties": {
"sasToken": {
"type": "string",
"minLength": 1,
"maxLength": 8192
}
}
}
]
}BosStorageDestinationWrite
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"provider",
"config",
"credentials"
],
"properties": {
"name": {
"$ref": "#/components/schemas/StorageDestinationName"
},
"provider": {
"type": "string",
"const": "bos"
},
"config": {
"$ref": "#/components/schemas/BosStorageConfig"
},
"credentials": {
"$ref": "#/components/schemas/StaticAccessKeyStorageCredentials",
"writeOnly": true
}
}
}BosStorageConfig
{
"type": "object",
"additionalProperties": false,
"required": [
"bucket",
"endpoint"
],
"properties": {
"bucket": {
"$ref": "#/components/schemas/StorageBucketName"
},
"endpoint": {
"$ref": "#/components/schemas/PublicHttpsStorageEndpoint"
},
"objectPrefix": {
"$ref": "#/components/schemas/StorageObjectPrefix"
}
}
}CreditBalance
{
"type": "object",
"additionalProperties": false,
"required": [
"balanceMicrocredits",
"reservedMicrocredits",
"availableMicrocredits",
"lifetimeGrantedMicrocredits",
"lifetimeUsedMicrocredits",
"lifetimeRefundedMicrocredits",
"lifetimePaymentReversedMicrocredits",
"updatedAt"
],
"properties": {
"balanceMicrocredits": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Signed settled balance equal to the sum of ledger deltas; verified provider reversals may make it negative."
},
"reservedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"availableMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "max(balanceMicrocredits - reservedMicrocredits, 0)."
},
"lifetimeGrantedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"lifetimeUsedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"lifetimeRefundedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Credits returned to the account by positive usage_refund entries."
},
"lifetimePaymentReversedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Absolute credits removed by provider payment_reversal entries."
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}CreditEntryType
{
"type": "string",
"enum": [
"trial_grant",
"subscription_grant",
"topup_grant",
"usage",
"usage_refund",
"payment_reversal",
"expiration",
"admin_adjustment",
"migration_opening_balance"
]
}CreditPolicy
{
"type": "object",
"additionalProperties": false,
"required": [
"unit",
"failedRequestsCharged",
"subscriptionGrantTiming",
"refundHandling",
"trialGrantMicrocredits",
"expiresAt"
],
"properties": {
"unit": {
"type": "string",
"const": "microcredit"
},
"failedRequestsCharged": {
"type": "boolean",
"const": false
},
"subscriptionGrantTiming": {
"type": "string",
"const": "invoice_paid"
},
"refundHandling": {
"type": "string",
"const": "append_only_reversal",
"description": "Failed requests release reservations; provider refunds create negative payment_reversal ledger entries."
},
"trialGrantMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}CreditTransaction
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type",
"deltaMicrocredits",
"balanceAfterMicrocredits",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^ctx_"
},
"type": {
"$ref": "#/components/schemas/CreditEntryType"
},
"deltaMicrocredits": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"balanceAfterMicrocredits": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Signed settled balance after this immutable entry."
},
"description": {
"type": "string"
},
"requestId": {
"type": [
"string",
"null"
]
},
"jobId": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}DataSource
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"category",
"modes",
"inputSchema",
"estimatedMicrocredits",
"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"
]
},
"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"
},
"estimatedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"requiresStorageDestination": {
"type": "boolean",
"description": "Whether query submission must reference an owned active storage destination."
}
}
}GcsStorageDestinationWrite
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"provider",
"config",
"credentials"
],
"properties": {
"name": {
"$ref": "#/components/schemas/StorageDestinationName"
},
"provider": {
"type": "string",
"const": "gcs"
},
"config": {
"$ref": "#/components/schemas/GcsStorageConfig"
},
"credentials": {
"$ref": "#/components/schemas/GcsStorageCredentials",
"writeOnly": true
}
}
}GcsStorageConfig
{
"type": "object",
"additionalProperties": false,
"required": [
"bucket",
"projectId"
],
"properties": {
"bucket": {
"$ref": "#/components/schemas/StorageBucketName"
},
"projectId": {
"type": "string",
"minLength": 6,
"maxLength": 63,
"pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
},
"objectPrefix": {
"$ref": "#/components/schemas/StorageObjectPrefix"
}
}
}GcsStorageCredentials
{
"type": "object",
"additionalProperties": false,
"required": [
"serviceAccount"
],
"properties": {
"serviceAccount": {
"$ref": "#/components/schemas/GcsServiceAccount"
}
}
}GcsServiceAccount
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"project_id",
"private_key_id",
"private_key",
"client_email",
"client_id",
"auth_uri",
"token_uri"
],
"properties": {
"type": {
"type": "string",
"const": "service_account"
},
"project_id": {
"type": "string"
},
"private_key_id": {
"type": "string"
},
"private_key": {
"type": "string",
"maxLength": 16384
},
"client_email": {
"type": "string",
"format": "email"
},
"client_id": {
"type": "string"
},
"auth_uri": {
"type": "string",
"const": "https://accounts.google.com/o/oauth2/auth"
},
"token_uri": {
"type": "string",
"const": "https://oauth2.googleapis.com/token"
},
"auth_provider_x509_cert_url": {
"type": "string"
},
"client_x509_cert_url": {
"type": "string"
},
"universe_domain": {
"type": "string"
}
}
}Health
{
"type": "object",
"additionalProperties": false,
"required": [
"status",
"service",
"version",
"time"
],
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"degraded"
]
},
"service": {
"type": "string"
},
"version": {
"type": "string"
},
"time": {
"type": "string",
"format": "date-time"
}
}
}HostedSession
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"url",
"expiresAt"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri",
"description": "Provider-hosted HTTPS URL. Production Stripe sessions use a Stripe-controlled *.stripe.com host; non-production fake adapters may use a reserved .test host. Web clients must validate the origin and redirect from a server-only boundary."
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}Invoice
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"number",
"status",
"currency",
"total",
"amountPaid",
"refundedAmount",
"createdAt"
],
"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."
},
"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"
}
}
}Job
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"source",
"status",
"progress",
"version",
"usage",
"createdAt",
"updatedAt",
"links"
],
"properties": {
"id": {
"type": "string",
"pattern": "^job_"
},
"source": {
"type": "string"
},
"status": {
"$ref": "#/components/schemas/JobStatus"
},
"progress": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"version": {
"type": "integer",
"minimum": 0
},
"usage": {
"$ref": "#/components/schemas/QueryUsage"
},
"error": {
"oneOf": [
{
"$ref": "#/components/schemas/SafeJobError"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"links": {
"type": "object",
"additionalProperties": false,
"required": [
"self"
],
"properties": {
"self": {
"type": "string"
},
"results": {
"type": [
"string",
"null"
]
}
}
}
}
}JobStatus
{
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed",
"cancelled"
]
}LegalAcceptanceRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"acceptedTerms",
"termsVersion",
"privacyVersion"
],
"properties": {
"acceptedTerms": {
"type": "boolean",
"const": true
},
"termsVersion": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"privacyVersion": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
}
}LoginRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 320
},
"password": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"writeOnly": true
},
"rememberMe": {
"type": "boolean",
"default": false,
"description": "Ignored for legal_acceptance and deletion_recovery Sessions, which always use a short fixed expiry."
}
}
}LoginResponse
{
"type": "object",
"additionalProperties": false,
"required": [
"account",
"csrfToken",
"sessionMode"
],
"properties": {
"account": {
"$ref": "#/components/schemas/Account"
},
"csrfToken": {
"type": "string",
"minLength": 32,
"readOnly": true
},
"sessionMode": {
"type": "string",
"enum": [
"full",
"legal_acceptance",
"deletion_recovery"
]
}
}
}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"
}
}
}OneTimeSigningSecret
{
"type": "object",
"additionalProperties": false,
"required": [
"signingSecret"
],
"properties": {
"signingSecret": {
"type": "string",
"readOnly": true,
"minLength": 32,
"description": "Plaintext signing secret returned only by this rotation transaction. The same authenticated idempotent replay may return it for five minutes.",
"x-secret-reveal": "once"
}
}
}OssStorageDestinationWrite
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"provider",
"config",
"credentials"
],
"properties": {
"name": {
"$ref": "#/components/schemas/StorageDestinationName"
},
"provider": {
"type": "string",
"const": "oss"
},
"config": {
"$ref": "#/components/schemas/OssStorageConfig"
},
"credentials": {
"$ref": "#/components/schemas/StaticAccessKeyStorageCredentials",
"writeOnly": true
}
}
}OssStorageConfig
{
"type": "object",
"additionalProperties": false,
"required": [
"bucket",
"endpoint",
"region"
],
"properties": {
"bucket": {
"$ref": "#/components/schemas/StorageBucketName"
},
"endpoint": {
"$ref": "#/components/schemas/PublicHttpsStorageEndpoint"
},
"region": {
"$ref": "#/components/schemas/StorageRegion"
},
"objectPrefix": {
"$ref": "#/components/schemas/StorageObjectPrefix"
}
}
}OutboundWebhookEventType
{
"type": "string",
"enum": [
"job.completed",
"job.failed",
"job.cancelled"
]
}Page
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination"
],
"properties": {
"data": {
"type": "array",
"items": {}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
}Pagination
{
"type": "object",
"additionalProperties": false,
"required": [
"hasMore",
"limit"
],
"properties": {
"nextCursor": {
"type": [
"string",
"null"
]
},
"hasMore": {
"type": "boolean"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
}
}Password
{
"type": "string",
"minLength": 12,
"maxLength": 128,
"writeOnly": true
}PlanCatalog
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"currency",
"billingAvailability"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Plan"
}
},
"currency": {
"type": "string",
"const": "USD"
},
"billingAvailability": {
"type": "string",
"enum": [
"available",
"unconfigured",
"unavailable"
]
},
"billingMessage": {
"type": [
"string",
"null"
],
"description": "Stable, non-sensitive explanation suitable for the Pricing and Billing UI."
}
}
}Plan
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"slug",
"name",
"description",
"includedMicrocredits",
"limits",
"prices",
"features"
],
"properties": {
"id": {
"type": "string",
"pattern": "^plan_"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"includedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Integer microcredits; 1 credit equals 1,000,000 microcredits."
},
"limits": {
"$ref": "#/components/schemas/PlanLimits"
},
"prices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlanPrice"
}
},
"features": {
"type": "array",
"items": {
"type": "string"
}
}
}
}PlanLimits
{
"type": "object",
"additionalProperties": false,
"required": [
"concurrency",
"maxBatchSize",
"maxPendingJobs"
],
"properties": {
"concurrency": {
"type": "integer",
"minimum": 1
},
"maxBatchSize": {
"type": "integer",
"minimum": 1
},
"maxPendingJobs": {
"type": "integer",
"minimum": 1
}
}
}PlanPrice
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"currency",
"unitAmount",
"creditsMicrocredits",
"type",
"interval"
],
"properties": {
"id": {
"type": "string",
"pattern": "^prc_"
},
"currency": {
"type": "string",
"const": "USD"
},
"unitAmount": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"creditsMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"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
]
}
}
}Problem
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code",
"requestId"
],
"properties": {
"type": {
"type": "string",
"format": "uri-reference"
},
"title": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"pattern": "^[a-z0-9_]+$"
},
"detail": {
"type": "string"
},
"requestId": {
"type": "string",
"pattern": "^req_"
},
"fieldErrors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldError"
}
}
}
}FieldError
{
"type": "object",
"additionalProperties": false,
"required": [
"field",
"code",
"message"
],
"properties": {
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}PublicHttpsStorageEndpoint
{
"type": "string",
"format": "uri",
"maxLength": 2048,
"pattern": "^https://",
"description": "Public HTTPS origin only; userinfo, path/query/fragment, special hostnames, and private/link-local DNS answers are rejected. Every DNS answer is validated before probe/upload and the connection is pinned to a validated address while preserving Host and TLS SNI."
}PublicLegalVersions
{
"type": "object",
"additionalProperties": false,
"required": [
"availability",
"termsVersion",
"privacyVersion"
],
"properties": {
"availability": {
"type": "string",
"enum": [
"configured",
"unconfigured"
]
},
"termsVersion": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 64
},
"privacyVersion": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 64
}
}
}PublicStatus
{
"type": "object",
"additionalProperties": false,
"required": [
"status",
"updatedAt",
"components"
],
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"degraded",
"outage"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"components": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicStatusComponent"
}
}
}
}PublicStatusComponent
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"status"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"operational",
"degraded",
"outage"
]
}
}
}QueryRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"source"
],
"properties": {
"source": {
"type": "string"
},
"query": {
"type": "string",
"maxLength": 2000
},
"params": {
"type": "object",
"additionalProperties": true
},
"context": {
"type": "array",
"deprecated": true,
"description": "V1 compatibility only; new clients should use params.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string"
},
"value": {}
}
}
},
"webhookEndpointId": {
"type": "string",
"pattern": "^whe_"
},
"storageDestinationId": {
"type": "string",
"pattern": "^dst_"
}
}
}QueryResults
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination"
],
"properties": {
"data": {
"type": "array",
"items": {}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
}QueryUsage
{
"type": "object",
"additionalProperties": false,
"required": [
"estimatedMicrocredits",
"chargedMicrocredits"
],
"properties": {
"estimatedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"chargedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"downloadedBytes": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
}RealtimeQueryResponse
{
"type": "object",
"additionalProperties": false,
"required": [
"requestId",
"source",
"status",
"results",
"usage",
"createdAt"
],
"properties": {
"requestId": {
"type": "string",
"pattern": "^req_"
},
"source": {
"type": "string"
},
"status": {
"type": "string",
"const": "completed"
},
"results": {
"type": "array",
"items": {}
},
"usage": {
"$ref": "#/components/schemas/QueryUsage"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}Reauthentication
{
"type": "object",
"additionalProperties": false,
"required": [
"reauthenticatedUntil"
],
"properties": {
"reauthenticatedUntil": {
"type": "string",
"format": "date-time"
}
}
}RegisterRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"email",
"password",
"acceptedTerms",
"termsVersion",
"privacyVersion"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"email": {
"type": "string",
"format": "email",
"maxLength": 320
},
"password": {
"$ref": "#/components/schemas/Password"
},
"acceptedTerms": {
"type": "boolean",
"const": true
},
"termsVersion": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Exact version rendered by the signup page; stale versions are rejected."
},
"privacyVersion": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Exact version rendered by the signup page; stale versions are rejected."
}
}
}RegisterResponse
{
"type": "object",
"additionalProperties": false,
"description": "Generic receipt returned for both a new account and a recoverable pending account. It intentionally omits identity data to limit account enumeration.",
"required": [
"emailVerificationRequired"
],
"properties": {
"emailVerificationRequired": {
"type": "boolean",
"const": true
}
}
}S3CompatibleStorageDestinationWrite
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"provider",
"config",
"credentials"
],
"properties": {
"name": {
"$ref": "#/components/schemas/StorageDestinationName"
},
"provider": {
"type": "string",
"const": "s3_compatible"
},
"config": {
"$ref": "#/components/schemas/S3CompatibleStorageConfig"
},
"credentials": {
"$ref": "#/components/schemas/AccessKeyStorageCredentials",
"writeOnly": true
}
}
}AccessKeyStorageCredentials
{
"type": "object",
"additionalProperties": false,
"required": [
"accessKeyId",
"secretAccessKey"
],
"properties": {
"accessKeyId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"secretAccessKey": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"sessionToken": {
"type": "string",
"minLength": 1,
"maxLength": 8192
}
}
}S3CompatibleStorageConfig
{
"type": "object",
"additionalProperties": false,
"required": [
"bucket",
"endpoint",
"region",
"forcePathStyle"
],
"properties": {
"bucket": {
"$ref": "#/components/schemas/StorageBucketName"
},
"endpoint": {
"$ref": "#/components/schemas/PublicHttpsStorageEndpoint"
},
"region": {
"$ref": "#/components/schemas/StorageRegion"
},
"forcePathStyle": {
"type": "boolean",
"default": true
},
"objectPrefix": {
"$ref": "#/components/schemas/StorageObjectPrefix"
}
}
}S3StorageDestinationWrite
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"provider",
"config",
"credentials"
],
"properties": {
"name": {
"$ref": "#/components/schemas/StorageDestinationName"
},
"provider": {
"type": "string",
"const": "s3"
},
"config": {
"$ref": "#/components/schemas/S3StorageConfig"
},
"credentials": {
"$ref": "#/components/schemas/AccessKeyStorageCredentials",
"writeOnly": true
}
}
}S3StorageConfig
{
"type": "object",
"additionalProperties": false,
"required": [
"bucket",
"region"
],
"properties": {
"bucket": {
"$ref": "#/components/schemas/StorageBucketName"
},
"region": {
"$ref": "#/components/schemas/StorageRegion"
},
"objectPrefix": {
"$ref": "#/components/schemas/StorageObjectPrefix"
}
}
}SafeJobError
{
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
}
}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",
"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"
}
}
}StaticAccessKeyStorageCredentials
{
"type": "object",
"additionalProperties": false,
"required": [
"accessKeyId",
"secretAccessKey"
],
"properties": {
"accessKeyId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"secretAccessKey": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
}
}StorageBucketName
{
"type": "string",
"minLength": 3,
"maxLength": 63,
"pattern": "^[a-z0-9][a-z0-9.-]*[a-z0-9]$"
}StorageDestination
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"provider",
"status",
"version",
"config",
"hasCredentials",
"lastTestStatus",
"lastTestedAt",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^dst_"
},
"name": {
"type": "string"
},
"provider": {
"type": "string",
"enum": [
"s3",
"s3_compatible",
"gcs",
"azure",
"bos",
"oss",
"tos"
]
},
"status": {
"type": "string",
"enum": [
"active",
"invalid",
"disabled"
]
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"config": {
"oneOf": [
{
"$ref": "#/components/schemas/S3StorageConfig"
},
{
"$ref": "#/components/schemas/S3CompatibleStorageConfig"
},
{
"$ref": "#/components/schemas/GcsStorageConfig"
},
{
"$ref": "#/components/schemas/AzureStorageConfig"
},
{
"$ref": "#/components/schemas/BosStorageConfig"
},
{
"$ref": "#/components/schemas/OssStorageConfig"
},
{
"$ref": "#/components/schemas/TosStorageConfig"
}
],
"description": "Provider-specific non-secret fields. The provider discriminator determines the branch."
},
"hasCredentials": {
"type": "boolean"
},
"lastTestStatus": {
"type": [
"string",
"null"
],
"enum": [
"succeeded",
"failed",
null
]
},
"lastTestedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}StorageDestinationName
{
"type": "string",
"minLength": 1,
"maxLength": 80
}StorageObjectPrefix
{
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "Relative object-key prefix; leading slash, backslash, and dot path segments are rejected."
}StorageRegion
{
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
}Subscription
{
"type": "object",
"description": "Effective entitlement projection. `status=payg` and `id=null` means no billing subscription record exists.",
"additionalProperties": false,
"required": [
"status",
"plan",
"cancelAtPeriodEnd"
],
"properties": {
"id": {
"type": [
"string",
"null"
],
"pattern": "^sub_"
},
"status": {
"type": "string",
"enum": [
"payg",
"trialing",
"active",
"past_due",
"grace",
"cancelled"
]
},
"plan": {
"$ref": "#/components/schemas/Plan"
},
"currentPeriodStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"currentPeriodEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelAtPeriodEnd": {
"type": "boolean"
},
"graceEndsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}TokenRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"token"
],
"properties": {
"token": {
"type": "string",
"minLength": 32,
"maxLength": 256,
"writeOnly": true
}
}
}TosStorageConfig
{
"type": "object",
"additionalProperties": false,
"required": [
"bucket",
"endpoint",
"region"
],
"properties": {
"bucket": {
"$ref": "#/components/schemas/StorageBucketName"
},
"endpoint": {
"$ref": "#/components/schemas/PublicHttpsStorageEndpoint"
},
"region": {
"$ref": "#/components/schemas/StorageRegion",
"description": "TOS signing region used with the configured native endpoint."
},
"objectPrefix": {
"$ref": "#/components/schemas/StorageObjectPrefix"
}
}
}TosStorageDestinationWrite
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"provider",
"config",
"credentials"
],
"properties": {
"name": {
"$ref": "#/components/schemas/StorageDestinationName"
},
"provider": {
"type": "string",
"const": "tos"
},
"config": {
"$ref": "#/components/schemas/TosStorageConfig"
},
"credentials": {
"$ref": "#/components/schemas/StaticAccessKeyStorageCredentials",
"writeOnly": true
}
}
}UpdateAccountRequest
{
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
}
}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."
}UpdateStorageDestinationRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"expectedVersion"
],
"minProperties": 2,
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"name": {
"$ref": "#/components/schemas/StorageDestinationName"
},
"provider": {
"type": "string",
"enum": [
"s3",
"s3_compatible",
"gcs",
"azure",
"bos",
"oss",
"tos"
]
},
"config": {
"oneOf": [
{
"$ref": "#/components/schemas/S3StorageConfig"
},
{
"$ref": "#/components/schemas/S3CompatibleStorageConfig"
},
{
"$ref": "#/components/schemas/GcsStorageConfig"
},
{
"$ref": "#/components/schemas/AzureStorageConfig"
},
{
"$ref": "#/components/schemas/BosStorageConfig"
},
{
"$ref": "#/components/schemas/OssStorageConfig"
},
{
"$ref": "#/components/schemas/TosStorageConfig"
}
]
},
"credentials": {
"writeOnly": true,
"anyOf": [
{
"$ref": "#/components/schemas/AccessKeyStorageCredentials"
},
{
"$ref": "#/components/schemas/StaticAccessKeyStorageCredentials"
},
{
"$ref": "#/components/schemas/GcsStorageCredentials"
},
{
"$ref": "#/components/schemas/AzureStorageCredentials"
}
]
}
}
}UsageEvent
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"requestId",
"jobId",
"source",
"mode",
"status",
"estimatedMicrocredits",
"chargedMicrocredits",
"durationMs",
"errorCode",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^use_"
},
"requestId": {
"type": "string",
"pattern": "^req_"
},
"jobId": {
"type": [
"string",
"null"
]
},
"source": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"realtime",
"async",
"batch"
]
},
"status": {
"type": "string",
"enum": [
"accepted",
"processing",
"completed",
"failed",
"cancelled"
]
},
"estimatedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"chargedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"durationMs": {
"type": "integer",
"minimum": 0
},
"errorCode": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}UsageSummary
{
"type": "object",
"additionalProperties": false,
"required": [
"from",
"to",
"requestCount",
"successCount",
"failedCount",
"chargedMicrocredits",
"buckets"
],
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
},
"requestCount": {
"type": "integer"
},
"successCount": {
"type": "integer"
},
"failedCount": {
"type": "integer"
},
"chargedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"buckets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UsageBucket"
}
}
}
}UsageBucket
{
"type": "object",
"additionalProperties": false,
"required": [
"key",
"requestCount",
"chargedMicrocredits"
],
"properties": {
"key": {
"type": "string"
},
"requestCount": {
"type": "integer"
},
"chargedMicrocredits": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
}WebhookDelivery
{
"type": "object",
"description": "One immutable HTTP attempt timeline entry. Outbound requests carry\n`X-FlashData-Event-Id`, `X-FlashData-Event-Type`, `X-FlashData-Delivery-Id`,\n`X-FlashData-Timestamp`, and `X-FlashData-Signature` headers. A pending entry can reach\nexactly one terminal status and cannot be overwritten by a duplicate processor.\n",
"additionalProperties": false,
"required": [
"id",
"endpointId",
"eventId",
"jobId",
"eventType",
"attempt",
"status",
"responseStatus",
"nextAttemptAt",
"createdAt",
"updatedAt",
"deliveredAt",
"durationMs",
"lastErrorCode"
],
"properties": {
"id": {
"type": "string",
"pattern": "^whd_"
},
"endpointId": {
"type": "string",
"pattern": "^whe_"
},
"eventId": {
"type": "string",
"pattern": "^owe_"
},
"jobId": {
"type": [
"string",
"null"
]
},
"eventType": {
"$ref": "#/components/schemas/WebhookDeliveryEventType"
},
"attempt": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"status": {
"type": "string",
"enum": [
"pending",
"delivered",
"failed",
"dead_letter"
]
},
"responseStatus": {
"type": [
"integer",
"null"
]
},
"nextAttemptAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"deliveredAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"durationMs": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"lastErrorCode": {
"type": [
"string",
"null"
]
}
}
}WebhookDeliveryDetail
{
"type": "object",
"additionalProperties": false,
"required": [
"delivery",
"attempts",
"payloadAvailable"
],
"properties": {
"delivery": {
"$ref": "#/components/schemas/WebhookDelivery"
},
"attempts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookDelivery"
}
},
"payloadAvailable": {
"type": "boolean"
}
}
}WebhookDeliveryEventType
{
"type": "string",
"enum": [
"job.completed",
"job.failed",
"job.cancelled",
"endpoint.test"
]
}WebhookEndpoint
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"url",
"status",
"events",
"secretLast4",
"failureCount",
"version",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^whe_"
},
"url": {
"type": "string",
"format": "uri"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"disabled"
]
},
"events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OutboundWebhookEventType"
}
},
"secretLast4": {
"type": "string"
},
"failureCount": {
"type": "integer",
"minimum": 0
},
"version": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}WebhookEndpointCreated
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"url",
"status",
"events",
"secretLast4",
"failureCount",
"version",
"createdAt",
"updatedAt",
"signingSecret"
],
"properties": {
"id": {
"type": "string",
"pattern": "^whe_"
},
"url": {
"type": "string",
"format": "uri"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"disabled"
]
},
"events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OutboundWebhookEventType"
}
},
"secretLast4": {
"type": "string"
},
"failureCount": {
"type": "integer",
"minimum": 0
},
"version": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"signingSecret": {
"type": "string",
"readOnly": true,
"minLength": 32,
"description": "Plaintext signing secret returned only by this creation transaction. The same authenticated idempotent replay may return it for five minutes.",
"x-secret-reveal": "once"
}
}
}