API Evangelist overlay for the idea.ai GenAI API

overlay: 1.0.0
info:
  title: API Evangelist overlay for the idea.ai GenAI API
  version: 1.0.0
  x-generated: '2026-11-04'
  x-method: generated
  x-source: openapi/creativefabrica-idea-ai-genai-openapi.yml
  x-rationale: >-
    Attach API Evangelist provenance, agent-oriented metadata and cross-links to
    the companion artifacts in this repository without mutating the captured
    spec. The underlying OpenAPI is already published by the provider with a
    bearer-token security scheme, detailed tag descriptions and schema
    documentation, so this overlay ONLY adds non-behavioural metadata
    (information-class fields): x-apievangelist blocks, x-idempotency hints
    grounded in the documented async flow, and x-related-artifact pointers
    into this repo. No request/response shapes are changed and no new
    operations are introduced.
extends: ../openapi/_original/creativefabrica-idea-ai-genai-openapi.yml

actions:
  - target: $.info
    description: >-
      Attach API Evangelist provenance to the info block so a consumer can
      trace this capture back to the source company (Creative Fabrica B.V.)
      and the aid used by apis.io.
    update:
      x-apievangelist:
        company: Creative Fabrica
        aid: creativefabrica
        api-aid: idea-ai-genai
        captured: '2026-11-04'
        source-pages:
          - https://www.idea.ai/platform/
          - https://www.idea.ai/platform/docs
        related-artifacts:
          - mcp/creativefabrica-mcp.yml
          - mcp/creativefabrica-tool-crosswalk.yml
          - llms/creativefabrica-llms.txt
          - skills/_index.yml

  - target: $.info
    description: >-
      Point to the human landing page for AI clients / agents that prefer to
      open a docs URL rather than render OpenAPI.
    update:
      x-landing-page: https://www.idea.ai/platform/
      x-mcp-endpoint: https://mcp.idea.ai/mcp

  - target: $.paths['/v1/generations'].post
    description: >-
      Mark createGeneration as safe to retry under an idempotency key — the
      provider's own flow IS an id-returning asynchronous create and the docs
      explicitly refund failed generations, so a client-side idempotency key
      is the natural retry primitive. Recorded as x-idempotency metadata;
      this is an agent-facing hint, not a behavioural change to the spec.
    update:
      x-idempotency:
        recommended: true
        header: Idempotency-Key
        scope: client-generated
        note: >-
          The provider does not document a server-enforced Idempotency-Key
          header. This x-idempotency hint is a convention the agent can
          enforce itself: generate a UUID, remember it with the submission,
          and if the POST fails before the 202 is read, retry with the same
          key only after confirming via listGenerations that no record
          exists. Billing is charged at creation time and failed generations
          are refunded automatically, so a true duplicate is a cost issue
          that the client alone can prevent.

  - target: $.paths['/v1/presets/{presetId}/generations'].post
    description: Same client-generated idempotency hint as createGeneration.
    update:
      x-idempotency:
        recommended: true
        header: Idempotency-Key
        scope: client-generated

  - target: $.paths['/v1/generations/{generationId}'].get
    description: >-
      Attach a polling hint grounded in the published async flow. The spec
      already documents three-day output retention; this hint helps an agent
      bound its poll budget.
    update:
      x-polling:
        terminal-statuses:
          - completed
          - failed
          - cancelled
        output-retention-hours: 72
        note: >-
          Poll until status is terminal. Output URLs stop resolving roughly
          72 hours after creation (counted from the UTC midnight following
          creation); the metadata record itself persists. Download outputs
          inside that window if you need to keep them.

  - target: $.components.securitySchemes.bearerAuth
    description: >-
      Enrich the bearer scheme description with the provider's own
      instructions for obtaining and rotating keys.
    update:
      x-key-provisioning:
        page: https://www.idea.ai/platform/get-api-key
        format: 'sk-...'
        transport: Authorization header, scheme Bearer
        note: >-
          Every request outside the MCP server path uses a bearer API key of
          the form sk-... issued at https://www.idea.ai/platform/get-api-key.
          The MCP server at https://mcp.idea.ai/mcp uses OAuth 2.1 instead;
          see mcp/creativefabrica-mcp.yml.