FlashData Catalog API

openapi: 3.2.0
info:
  title: FlashData Customer Catalog 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: Catalog
paths:
  /catalog/sources:
    get:
      operationId: listPublicDataSources
      tags:
      - Catalog
      summary: List public source capabilities without account-specific pricing
      security: []
      responses:
        '200':
          description: Public source catalog
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControlPublic'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataSource'
  /plans:
    get:
      operationId: listPlans
      tags:
      - Catalog
      summary: List public USD plans and prices
      security: []
      responses:
        '200':
          description: Public plan catalog
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControlPublic'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanCatalog'
  /legal/current:
    get:
      operationId: getCurrentLegalVersions
      tags:
      - Catalog
      summary: Read the current Terms and Privacy versions required for signup
      security: []
      responses:
        '200':
          description: Current legal version catalog
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControlPublic'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicLegalVersions'
components:
  schemas:
    Plan:
      type: object
      additionalProperties: false
      required:
      - id
      - slug
      - name
      - description
      - includedCredits
      - limits
      - prices
      - features
      - usagePrices
      properties:
        id:
          type: string
          pattern: ^plan_
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        includedCredits:
          type: number
          minimum: 0
          multipleOf: 0.001
          description: Credits included in each paid subscription cycle; zero for Pay As You Go.
        limits:
          $ref: '#/components/schemas/PlanLimits'
        prices:
          type: array
          items:
            $ref: '#/components/schemas/PlanPrice'
        features:
          type: array
          items:
            type: string
        usagePrices:
          $ref: '#/components/schemas/PlanUsagePrices'
    DataSource:
      type: object
      additionalProperties: false
      required:
      - id
      - name
      - category
      - product
      - modes
      - inputSchema
      - estimatedCredits
      - requiresStorageDestination
      properties:
        id:
          type: string
          enum:
          - google_search
          - google_images
          - google_news
          - google_shopping
          - google_videos
          - google_places
          - youtube_search
          - youtube_search_extended
          - youtube_metadata
          - youtube_transcript
          - youtube_captions
          - youtube_trainability
          - youtube_channel
          - youtube_suggestions
          - youtube_download
        name:
          type: string
        category:
          type: string
          enum:
          - google
          - youtube
        product:
          type: string
          enum:
          - google_search
          - youtube_data
          - youtube_download
        modes:
          type: array
          minItems: 1
          uniqueItems: true
          description: Only modes backed by a real adapter or consumer in the current release
          items:
            type: string
            enum:
            - realtime
            - async
            - batch
        inputSchema:
          type: object
          additionalProperties: true
          description: JSON Schema used by the Playground and generated clients
        estimatedCredits:
          type: number
          minimum: 0
          multipleOf: 0.001
        requiresStorageDestination:
          type: boolean
          description: Whether query submission must include per-request storage configuration.
    PlanUsagePrices:
      type: object
      additionalProperties: false
      required:
      - googlePer1kCents
      - youtubePer1kCents
      - downloadPerTbCents
      properties:
        googlePer1kCents:
          type: integer
          minimum: 0
          description: Google request price per 1,000 successful requests, in USD cents.
        youtubePer1kCents:
          type: integer
          minimum: 0
          description: Standard YouTube request price per 1,000 successful requests, in USD cents.
        downloadPerTbCents:
          type: integer
          minimum: 0
          description: Download price per decimal TB (1,000,000,000,000 bytes), in USD cents.
    PlanPrice:
      type: object
      additionalProperties: false
      required:
      - id
      - currency
      - unitAmount
      - credits
      - type
      - interval
      properties:
        id:
          type: string
          pattern: ^prc_
        currency:
          type: string
          const: USD
        unitAmount:
          type: integer
          minimum: 0
          description: USD cents
        credits:
          type: number
          minimum: 0
          multipleOf: 0.001
          description: Credits granted by a successful one-time top-up; zero for recurring prices.
        type:
          type: string
          enum:
          - recurring
          - one_time
        interval:
          type:
          - string
          - 'null'
          enum:
          - month
          - year
          - null
    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
    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
    PlanCatalog:
      type: object
      additionalProperties: false
      required:
      - data
      - currency
      - billingAvailability
      - creditValueUsd
      properties:
        trialOffer:
          description: Current one-time trial allowance expressed as alternative PAYG usage amounts. Eligibility and approval are required. The amounts share one balance and are not additive. Null when a reliable estimate is unavailable. This is not an account eligibility decision or a promise of immediate credit issuance.
          oneOf:
          - $ref: '#/components/schemas/PublicTrialOffer'
          - type: 'null'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Plan'
        currency:
          type: string
          const: USD
        creditValueUsd:
          type: number
          exclusiveMinimum: 0
          description: Fixed USD value of one credit, used to preview custom top-ups. The server computes the credited amount.
        billingAvailability:
          type: string
          enum:
          - available
          - unconfigured
          - unavailable
        billingMessage:
          type:
          - string
          - 'null'
          description: Stable, non-sensitive explanation suitable for the Pricing and Billing UI.
    PublicTrialOffer:
      type: object
      additionalProperties: false
      required:
      - googleSearchRequests
      - youtubeDataRequests
      - downloadGigabytes
      properties:
        maxApiRequests:
          type: integer
          minimum: 0
          description: Maximum free API calls when the entire trial grant is spent on the lowest-cost per-request API at current Pay as you go rates. Other APIs may allow fewer calls. Downloads are billed by delivered bytes and excluded from this count.
        googleSearchRequests:
          type: integer
          minimum: 0
          description: Requests if the entire grant is spent on Google sources, using the highest current source rate.
        youtubeDataRequests:
          type: integer
          minimum: 0
          description: Standard YouTube requests, excluding Extended Search, using the highest current source rate.
        downloadGigabytes:
          type: number
          minimum: 0
          description: Approximate delivered media volume in decimal GB (1 GB = 1000000000 bytes). Zero when the grant cannot cover the initial download reservation. Completion also depends on per-job reservations and settlement.
  headers:
    CacheControlPublic:
      description: Public cache duration and stale-response policy
      schema:
        type: string
        const: public, max-age=60, stale-while-revalidate=300
  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.