FlashData Credits API

openapi: 3.2.0
info:
  title: FlashData Customer Credits API
  version: 0.2.0-draft
  summary: FlashData control-plane API contract
  description: Google search, YouTube data and media downloads, with endpoints for jobs, accounts, API keys and billing. See /docs for request examples and setup guides.
  contact:
    name: FlashData Engineering
servers:
- url: https://api.flashdata.dev/v2
  description: Management API
tags:
- name: Credits
paths:
  /api-access/balance:
    get:
      operationId: getApiAccessBalance
      tags:
      - Credits
      summary: Read the live account balance using an API key
      description: Read the current credit balance shared by all API keys in your account. Active reservations can reduce the available balance. This request costs no Credits and takes no query parameters or body. Responses are private and are not cached; account-read rate limits apply.
      security:
      - dataApiKey: []
      responses:
        '200':
          description: Signed balance and nonnegative available Credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAccessBalance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          description: Too many account reads; retry after the rate-limit window
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api-access/pricing:
    get:
      operationId: getApiAccessPricing
      tags:
      - Credits
      summary: Read actual account prices for sources authorized by the API key
      description: Read your account rates for sources allowed by the API key. A null price means that source is unavailable. request_count counts queries, not returned items; download rates are per TB (10^12 bytes). Estimates do not reserve Credits or capacity. This request costs no Credits. Responses are private and are not cached; account-read rate limits apply.
      security:
      - dataApiKey: []
      parameters:
      - name: source
        in: query
        description: A source granted to this key; omit to read all granted sources.
        schema:
          $ref: '#/components/schemas/ApiAccessSource'
      - name: request_count
        in: query
        description: Decimal integer number of calls; does not estimate download size.
        schema:
          type: integer
          minimum: 1
          maximum: 100000
          default: 1
      responses:
        '200':
          description: Account plan and source-specific prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAccessPricing'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          description: Too many account reads; retry after the rate-limit window
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api-access/limits:
    get:
      operationId: getApiAccessLimits
      tags:
      - Credits
      summary: Read account plan limits and current pending jobs using an API key
      description: Read your concurrency, batch-size and pending-job limits, plus the current pending count. These values help plan requests but do not reserve capacity. This request costs no Credits and takes no query parameters or body. Responses are private and are not cached; account-read rate limits apply.
      security:
      - dataApiKey: []
      responses:
        '200':
          description: Plan ceilings and current pending count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAccessLimits'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          description: Too many account reads; retry after the rate-limit window
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /usage:
    get:
      operationId: getApiKeyUsage
      tags:
      - Credits
      summary: Read account usage for sources authorized by the API key
      description: 'Free read, authenticated only by X-API-Key. Includes all account keys but

        only sources granted to the calling key. Does not return query text, keys,

        payment details or other accounts. Defaults to seven days; maximum 31 days.

        Dates must use UTC Z timestamps. From is inclusive and to exclusive;

        both are rounded down to minutes. With from alone, to defaults to from + 7 days.

        With neither, to is the start of the next minute. Aggregates are eventually

        consistent; even updating=false does not guarantee all recent events are ingested.

        Read limit: 60 requests per minute per client IP.'
      security:
      - dataApiKey: []
      parameters:
      - name: source
        in: query
        description: An exact catalog source granted to the calling key; omitted means all granted sources.
        schema:
          type: string
          enum:
          - google_search
          - google_images
          - google_news
          - google_shopping
          - google_videos
          - google_places
          - youtube_search
          - youtube_search_extended
          - youtube_metadata
          - youtube_transcript
          - youtube_captions
          - youtube_trainability
          - youtube_channel
          - youtube_suggestions
          - youtube_download
      - name: from
        in: query
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Scoped request counts and charged Credits, with freshness information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyUsage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          description: Too many usage reads; retry after the rate-limit window
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /credits/balance:
    get:
      operationId: getCreditBalance
      tags:
      - Credits
      summary: Read current available and reserved credits
      security:
      - cookieSession: []
      responses:
        '200':
          description: Credit balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalance'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credits/policy:
    get:
      operationId: getCreditPolicy
      tags:
      - Credits
      summary: Read the effective account credit grant and charging policy
      security:
      - cookieSession: []
      responses:
        '200':
          description: Effective credit policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditPolicy'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credits/transactions:
    get:
      operationId: listCreditTransactions
      tags:
      - Credits
      summary: List credit ledger entries
      security:
      - cookieSession: []
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: type
        in: query
        schema:
          $ref: '#/components/schemas/CreditEntryType'
      responses:
        '200':
          description: Ledger entries
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Page'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/CreditTransaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CreditEntryType:
      type: string
      enum:
      - subscription_grant
      - topup_grant
      - payment_reversal
      - admin_adjustment
      - trial_grant
    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'
    ApiAccessSource:
      type: string
      enum:
      - google_search
      - google_images
      - google_news
      - google_shopping
      - google_videos
      - google_places
      - youtube_search
      - youtube_search_extended
      - youtube_metadata
      - youtube_transcript
      - youtube_captions
      - youtube_trainability
      - youtube_channel
      - youtube_suggestions
      - youtube_download
    ApiAccessPricing:
      type: object
      additionalProperties: false
      required:
      - unit
      - plan
      - requestCount
      - prices
      - note
      properties:
        unit:
          type: string
          const: Credits
        plan:
          $ref: '#/components/schemas/ApiAccessPlan'
        requestCount:
          type: integer
          minimum: 1
          maximum: 100000
        prices:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - source
            - available
            - estimatedCredits
            properties:
              source:
                $ref: '#/components/schemas/ApiAccessSource'
              available:
                type: boolean
              creditsPerRequest:
                type:
                - number
                - 'null'
                minimum: 0
              estimatedCredits:
                type:
                - number
                - 'null'
                minimum: 0
                description: Null for downloads or missing pricing.
              billingUnit:
                type: string
                const: TB
              bytesPerUnit:
                type: integer
                const: 1000000000000
              creditsPerTb:
                type:
                - number
                - 'null'
                minimum: 0
              note:
                type: string
        note:
          type: string
    ApiAccessPlan:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        type:
          type: string
        billingMode:
          type: string
        status:
          type: string
    FieldError:
      type: object
      additionalProperties: false
      required:
      - field
      - code
      - message
      properties:
        field:
          type: string
        code:
          type: string
        message:
          type: string
    CreditPolicy:
      type: object
      additionalProperties: false
      required:
      - unit
      - failedRequestsCharged
      - subscriptionGrantTiming
      - refundHandling
      properties:
        unit:
          type: string
          const: credit
        failedRequestsCharged:
          type: boolean
          const: false
        subscriptionGrantTiming:
          type: string
          const: invoice_paid
        refundHandling:
          type: string
          const: append_only_reversal
          description: Failed requests are refunded; verified provider refunds remove the proportional Credits through immutable transactions.
    CreditBalance:
      type: object
      additionalProperties: false
      required:
      - balanceCredits
      - reservedCredits
      - availableCredits
      - lifetimeGrantedCredits
      - lifetimeUsedCredits
      - lifetimeRefundedCredits
      - lifetimePaymentReversedCredits
      - updatedAt
      properties:
        balanceCredits:
          type: number
          multipleOf: 0.001
          description: Signed settled balance after grants, usage, refunds and provider reversals.
        reservedCredits:
          type: number
          minimum: 0
          multipleOf: 0.001
        availableCredits:
          type: number
          minimum: 0
          multipleOf: 0.001
          description: max(balanceCredits, 0).
        lifetimeGrantedCredits:
          type: number
          minimum: 0
          multipleOf: 0.001
        lifetimeUsedCredits:
          type: number
          minimum: 0
          multipleOf: 0.001
        lifetimeRefundedCredits:
          type: number
          minimum: 0
          multipleOf: 0.001
          description: Credits returned to the account after failed usage.
        lifetimePaymentReversedCredits:
          type: number
          minimum: 0
          multipleOf: 0.001
          description: Absolute Credits removed after verified provider refunds or chargebacks.
        updatedAt:
          type: string
          format: date-time
    Page:
      type: object
      additionalProperties: false
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items: {}
        pagination:
          $ref: '#/components/schemas/Pagination'
    CreditTransaction:
      type: object
      additionalProperties: false
      required:
      - id
      - type
      - deltaCredits
      - balanceAfterCredits
      - createdAt
      properties:
        id:
          type: string
          pattern: ^ctx_
        type:
          $ref: '#/components/schemas/CreditEntryType'
        deltaCredits:
          type: number
          multipleOf: 0.001
        balanceAfterCredits:
          type:
          - number
          - 'null'
          multipleOf: 0.001
          description: Signed settled balance after this immutable transaction, when recorded.
        description:
          type: string
        requestId:
          type:
          - string
          - 'null'
        jobId:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
    Pagination:
      type: object
      additionalProperties: false
      required:
      - hasMore
      - limit
      properties:
        nextCursor:
          type:
          - string
          - 'null'
        previousCursor:
          type:
          - string
          - 'null'
        hasMore:
          type: boolean
        limit:
          type: integer
          minimum: 1
          maximum: 100
    ApiKeyUsage:
      type: object
      additionalProperties: false
      required:
      - scope
      - unit
      - from
      - to
      - observedAt
      - totals
      - bySource
      - updating
      - note
      properties:
        scope:
          type: string
          const: account_authorized_sources
        unit:
          type: string
          const: Credits
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        observedAt:
          type: string
          format: date-time
        totals:
          $ref: '#/components/schemas/UsageCounts'
        bySource:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - source
            - requests
            - completed
            - failed
            - credits
            properties:
              source:
                type: string
              requests:
                type: integer
                minimum: 0
              completed:
                type: integer
                minimum: 0
              failed:
                type: integer
                minimum: 0
              credits:
                type: number
                minimum: 0
        updating:
          type: boolean
        note:
          type: string
    ApiAccessLimits:
      type: object
      additionalProperties: false
      required:
      - scope
      - plan
      - limits
      - current
      - note
      properties:
        scope:
          type: string
          const: account
        plan:
          $ref: '#/components/schemas/ApiAccessPlan'
        limits:
          type: object
          additionalProperties: false
          properties:
            concurrency:
              type: integer
              minimum: 0
            batchSize:
              type: integer
              minimum: 0
            pendingJobs:
              type: integer
              minimum: 0
        current:
          type: object
          additionalProperties: false
          required:
          - pendingJobs
          properties:
            pendingJobs:
              type: integer
              minimum: 0
        note:
          type: string
    ApiAccessBalance:
      type: object
      additionalProperties: false
      required:
      - scope
      - unit
      - balanceCredits
      - availableCredits
      - updatedAt
      - note
      properties:
        scope:
          type: string
          const: account
        unit:
          type: string
          const: Credits
        balanceCredits:
          type: number
          description: Signed live balance; in-flight reservations may already be reflected.
        availableCredits:
          type: number
          minimum: 0
          description: max(balanceCredits, 0).
        updatedAt:
          type:
          - string
          - 'null'
        note:
          type: string
    UsageCounts:
      type: object
      additionalProperties: false
      required:
      - requests
      - completed
      - failed
      - credits
      properties:
        requests:
          type: integer
          minimum: 0
        completed:
          type: integer
          minimum: 0
        failed:
          type: integer
          minimum: 0
        credits:
          type: number
          minimum: 0
          description: Charged Credits in the current aggregate; pending work may not be finally settled.
  responses:
    Unauthorized:
      description: Authentication required or invalid
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ValidationError:
      description: Request validation failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: Authenticated but not permitted, or CSRF validation failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ServiceUnavailable:
      description: A required dependency or catalog is temporarily unavailable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  parameters:
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
        maxLength: 512
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
  securitySchemes:
    dataApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: FlashData API key. Job access is restricted to the key's source scopes.
    agentRegistrationProof:
      type: http
      scheme: bearer
      description: Persist a cryptographically random 32-byte base64url proof and exact request BEFORE sending; recover only with the same proof and body. Not an OAuth token.
    cookieSession:
      type: apiKey
      in: cookie
      name: __Host-fd_session
      description: Opaque Web session. The browser cannot read this cookie.
    agentSetupCredential:
      type: http
      scheme: bearer
      description: Temporary setup credential for status and claim creation only. Not a data API key.
    csrfToken:
      type: apiKey
      in: header
      name: X-CSRF-Token
    agentIdentityKey:
      type: http
      scheme: bearer
      description: Ordinary FlashData API key in Authorization Bearer, only on agent identity. Data queries use X-API-Key instead.
    agentHandoffProof:
      type: http
      scheme: bearer
      description: Proof used to recover the owner key and acknowledge installation. Never sent to a data query.