API Evangelist enhancements for the Galatea Bio Octopod Ancestry API

# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Galatea Bio Octopod Ancestry API
  version: 1.0.0
extends: openapi/galatea-bio-octopod-openapi.yml
x-generated: '2026-08-16'
x-method: generated
x-source: >-
  Enhancements derived from the GalateaBio Ancestry API documentation, the first-party
  GalateaBio/octopod-cli client library, and live probes of api.galatea.bio. The harvested Swagger
  document is never mutated; every addition below is expressed as an overlay action.
actions:
- target: $.info
  update:
    description: >-
      REST API for the Galatea Bio Octopod platform. Upload genomic source files (VCF) over HTTPS or
      SFTP, submit execution orders against named analysis models including the StrataRisk polygenic
      risk score, track progress through HMAC-signed webhooks, and download ancestry, PRS, JSON and
      PDF report results. Bearer-token authentication; page/page_size pagination; a flat
      {"detail": "..."} error envelope.
    contact:
      name: Galatea Bio
      email: info@galatea.bio
      url: https://galatea.bio/
    x-documentation: https://docs.galatea.bio/
    x-apievangelist-profile: https://apis.io/provider/galatea-bio
    x-apievangelist-harvested: '2026-08-16'
    x-apievangelist-source: https://api.galatea.bio/swagger/?format=openapi
- target: $
  update:
    x-environments:
    - name: production
      base_url: https://api.galatea.bio/api/v1
      webhook_sender_host: api.galatea.bio
    - name: sandbox
      base_url: https://api.sandbox.galatea.bio/api/v1
      webhook_sender_host: api.sandbox.galatea.bio
    x-spec-notes:
      original_format: Swagger 2.0, generated by drf-yasg
      named_schemas: 0
      note: >-
        The source document declares an empty definitions block, so every schema is inlined per
        operation and nothing is reusable. Consumers wanting named types must reconstruct them -
        see data-model/galatea-bio-data-model.yml.
- target: $.securityDefinitions.Bearer
  update:
    description: >-
      JWT bearer token sent as "Authorization: Bearer <token>". Either a long-lived organization API
      key minted by an admin via POST /organizations/{organization_id}/generate-api-key, or a
      short-lived access token obtained from POST /users/auth and renewed via POST /users/refresh.
    x-token-modes: [organization-api-key, password-derived-access-token]
    x-mfa: true
- target: $
  update:
    x-conventions:
      pagination:
        style: page-number
        request: [page, page_size]
        response: [count, next, previous, results]
      identifiers: uuid4, no type prefix
      error_envelope:
        field: detail
        rfc9457: false
      versioning:
        scheme: uri-path
        current: v1
      idempotency:
        supported: false
      rate_limits:
        documented: false
- target: $
  update:
    x-webhooks:
      signature_header: X-Octopod-Signature
      algorithm: base64(HMAC-SHA256(secret, sender_host + raw_body))
      expected_response: HTTP 200, empty body
      events:
      - source_file_validation_completed
      - order_moved_to_completed_state
      docs: https://docs.galatea.bio/#recipe-handling-webhooks-deliveries
      artifact: asyncapi/galatea-bio-octopod-webhooks.yml
- target: $.paths['/exec/orders'].post
  update:
    summary: Submit an execution order
    description: >-
      Runs one named analysis model against one validated source file. Consumes organization
      credits. Returns immediately with an order object; completion arrives via the
      order_moved_to_completed_state webhook or by polling GET /exec/orders with filter. Not
      idempotent - resubmitting creates another order and another charge.
    x-consequence: write
    x-billable: true
    x-idempotent: false
- target: $.paths['/exec/cancel'].post
  update:
    summary: Cancel a running execution order
    x-consequence: destructive
- target: $.paths['/data/files/upload'].post
  update:
    summary: Upload a genomic source file
    description: >-
      Multipart upload limited to 50 MB. Larger files must be delivered over SFTP, which the
      provider documents as the preferred path for any size. File names may contain only letters,
      digits, spaces and the -+_. symbols. Validation is asynchronous; completion arrives via the
      source_file_validation_completed webhook.
    x-max-request-size: 50MB
    x-alternative-transport: sftp
- target: $.paths['/data/files/{source_file_id}'].delete
  update:
    summary: Delete a genomic source file
    x-consequence: destructive
    x-irreversible: true
- target: $.paths['/users/auth'].post
  update:
    summary: Log in and obtain access, refresh and websocket tokens
    description: >-
      Returns {"refresh": ..., "access": ..., "websocket_access": ...}. The access token is
      short-lived. Where MFA is enabled the flow continues through POST /users/confirm with the
      mfa_session_id and a numeric code.
- target: $
  update:
    x-data-sensitivity:
      class: human genomic data
      regulatory_context: >-
        Operated from a CLIA-CMS certified, CAP-accredited high-complexity clinical laboratory.
        Payloads reference identifiable genomic samples and clinical polygenic risk reports.
      agent_guidance: agentic-access/galatea-bio-agentic-access.yml
- target: $
  update:
    x-apievangelist-gaps:
    - Swagger 2.0 rather than OpenAPI 3.x
    - definitions block is empty; zero reusable component schemas
    - no operation summaries in the source document, only short descriptions
    - errors are not RFC 9457 application/problem+json
    - no 429 response and no rate-limit headers declared
    - no Sunset or Deprecation header support
    - no idempotency contract on order submission
    - no in-spec request or response examples
    - '"pip install octopod" in the docs installs an unrelated PyPI package'