FlashData Account API

openapi: 3.2.0
info:
  title: FlashData Customer Account 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: Account
paths:
  /oauth/connections:
    get:
      operationId: listOAuthConnections
      tags:
      - Account
      summary: List the current account's connected apps
      description: Full session required. Empty when the account has no connected apps. Response is no-store.
      security:
      - cookieSession: []
      responses:
        '200':
          description: Connected apps
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthConnection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /oauth/connections/{grantId}:
    delete:
      operationId: revokeOAuthConnection
      tags:
      - Account
      summary: Revoke a connected app and its dedicated API key
      description: Full session, CSRF and allowed Origin required. Account ownership is enforced. Response is no-store.
      security:
      - cookieSession: []
        csrfToken: []
      parameters:
      - name: grantId
        in: path
        required: true
        schema:
          type: string
          pattern: ^oag_[A-Za-z0-9_-]{8,}$
      responses:
        '204':
          description: Authorization revoked
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /account:
    get:
      operationId: getAccount
      tags:
      - Account
      summary: Read account settings
      security:
      - cookieSession: []
      responses:
        '200':
          description: Account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: updateAccount
      tags:
      - Account
      summary: Update profile settings
      security:
      - cookieSession: []
        csrfToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountRequest'
      responses:
        '200':
          description: Updated account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      operationId: deleteAccount
      tags:
      - Account
      summary: Schedule account deletion and revoke all existing sessions and API Keys
      description: Administrator accounts must have their platform role revoked through the audited operator workflow before deletion can be scheduled. A unique active deletion request is the natural idempotency boundary. Concurrent authenticated schedules return the same request. After Session revocation, a lost response is recovered by logging into deletion_recovery mode and reading GET /account/deletion; revoked Sessions are never accepted for replay.
      security:
      - cookieSession: []
        csrfToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - password
              - confirmation
              properties:
                password:
                  type: string
                  minLength: 1
                  maxLength: 128
                  writeOnly: true
                confirmation:
                  type: string
                  const: DELETE
      responses:
        '202':
          description: Deletion scheduled; active sessions and keys revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDeletionRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
  /account/deletion:
    get:
      operationId: getAccountDeletion
      tags:
      - Account
      summary: Read the current account deletion request
      x-session-modes:
      - deletion_recovery
      security:
      - cookieSession: []
      responses:
        '200':
          description: Current deletion request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDeletionRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: cancelAccountDeletion
      tags:
      - Account
      summary: Cancel a scheduled deletion during the grace period
      description: 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.
      x-requires-recent-auth: true
      x-session-modes:
      - deletion_recovery
      security:
      - cookieSession: []
        csrfToken: []
      responses:
        '204':
          description: Deletion cancelled, account reactivated, and recovery Session rotated according to the legal-acceptance gate
          headers:
            Set-Cookie:
              $ref: '#/components/headers/SessionCookie'
            Cache-Control:
              $ref: '#/components/headers/CacheControlNoStore'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /account/legal-acceptances:
    post:
      operationId: acceptCurrentLegalTerms
      tags:
      - Account
      summary: Accept the currently published Terms and Privacy versions
      description: Appends an immutable legal acceptance, clears the migration gate, and rotates the Session. Stale submitted versions are rejected.
      x-session-modes:
      - legal_acceptance
      security:
      - cookieSession: []
        csrfToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegalAcceptanceRequest'
      responses:
        '200':
          description: Legal acceptance recorded and Session rotated to full mode
          headers:
            Set-Cookie:
              $ref: '#/components/headers/SessionCookie'
            Cache-Control:
              $ref: '#/components/headers/CacheControlNoStore'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    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
    OAuthConnection:
      type: object
      additionalProperties: false
      required:
      - id
      - clientName
      - scope
      - status
      - createdAt
      - expiresAt
      properties:
        id:
          type: string
          pattern: ^oag_[A-Za-z0-9_-]{8,}$
        clientName:
          type: string
        scope:
          type: string
          enum:
          - mcp:research
        status:
          type: string
          enum:
          - active
          - expired
          - revoked
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
    FieldError:
      type: object
      additionalProperties: false
      required:
      - field
      - code
      - message
      properties:
        field:
          type: string
        code:
          type: string
        message:
          type: string
    LoginResponse:
      type: object
      additionalProperties: false
      required:
      - account
      - csrfToken
      - sessionMode
      properties:
        account:
          $ref: '#/components/schemas/Account'
        csrfToken:
          type: string
          minLength: 32
          readOnly: true
        sessionMode:
          type: string
          enum:
          - full
          - email_verification
          - legal_acceptance
          - deletion_recovery
    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
    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'
    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.
    UpdateAccountRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        timezone:
          type: string
          minLength: 1
          maxLength: 80
  responses:
    Unauthorized:
      description: Authentication required or invalid
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: Resource not found or not owned by the caller
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ValidationError:
      description: Request validation failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: Resource state or idempotency conflict
      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'
  headers:
    RequestId:
      description: Stable request correlation ID
      schema:
        type: string
        pattern: ^req_
    SessionCookie:
      description: Opaque session cookie with `Secure; HttpOnly; SameSite=Lax; Path=/`, High priority, and no Domain attribute
      schema:
        type: string
        pattern: ^__Host-fd_session=fds_[A-Za-z0-9_-]{43}; Path=/; Expires=[^;]+; HttpOnly; Secure; Priority=High; SameSite=Lax$
    CacheControlNoStore:
      description: Prevents storage of sensitive or state-changing responses by browsers and intermediaries
      schema:
        type: string
        const: no-store
  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.