overlay: 1.0.0
info:
  title: API Evangelist enhancements — BlueOcean Spark platform API
  version: 1.0.0
extends: ../openapi/blueocean-spark-platform-openapi.json
x-provenance:
  generated: '2026-08-13'
  method: generated
  source: >-
    Generated by the API Evangelist enrichment pipeline over the verbatim FastAPI-generated
    OpenAPI 3.1.0 served at https://poseidon.blueocean.ai/api/openapi.json. The original is
    preserved unmodified in openapi/_original/; this overlay records only our additions.
  note: >-
    The single load-bearing change here is servers[]. The published contract declares the
    RELATIVE server "/api", which names no host — a document fetched and saved to disk becomes
    uncallable. The absolute base https://poseidon.blueocean.ai/api is established from two
    independent sources: the host the document was fetched from, and the app.blueocean.ai
    product login bundle, which hardcodes https://poseidon.blueocean.ai/api as its API base.
actions:
  - target: $.servers
    description: Replace the relative server with the absolute production base.
    update:
      - url: https://poseidon.blueocean.ai/api
        description: >-
          Production base for the BlueOcean Spark platform backend, as used by the
          app.blueocean.ai web application. Not a documented public developer API.
  - target: $.info
    description: >-
      Replace the FastAPI default title/version with the product this contract actually
      describes, and record what the contract is and is not.
    update:
      title: BlueOcean Spark Platform API
      version: 0.1.0
      description: >-
        The application backend for BlueOcean's Spark agentic marketing assistant, covering
        saved prompts and prompt analytics, "Siren" recurring schedules, session document
        upload, persistent user memory, conversation history and widget state, and the
        brokering of third-party MCP server connections through Pipedream Connect.
        THIS IS NOT A PUBLISHED DEVELOPER API. BlueOcean documents no developer program, no
        authentication, no pricing and no rate limits; this contract is the FastAPI framework's
        auto-generated description of the backend the web application calls, reachable
        anonymously at the time of capture. It is profiled here as an observed public artifact,
        not as an integration surface API Evangelist recommends calling.
      x-api-evangelist-caveat: >-
        info.title and info.version in the original are FastAPI defaults, not authored values.
      contact:
        name: BlueOcean
        url: https://www.blueocean.ai/
  - target: $.externalDocs
    description: Point at the company site, since no API documentation is published.
    update:
      url: https://www.blueocean.ai/
      description: >-
        BlueOcean company website. No developer portal, API reference, getting-started guide
        or changelog is published (/api, /developers, /docs, /changelog all 404).
  - target: $
    description: Record the cross-cutting findings the contract itself does not state.
    update:
      x-api-evangelist-findings:
        security_schemes_declared: 0
        operations: 72
        paths: 63
        documented_status_codes: ['200', '422']
        auth: >-
          No securityScheme and no operation-level security. Caller identity is carried as
          user_id / account_id request parameters.
        idempotency: none
        pagination: none
        rate_limit_headers: none
        response_schemas: >-
          No 200 response in the document declares a schema, so no consumer can generate a
          typed client or predict a payload.