API Evangelist enhancements for the Daloopa API v3

# 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 Daloopa API v3
  version: 1.0.0
  x-generated: '2026-08-11'
  x-method: generated
  x-source: >-
    Generated by the API Evangelist enrichment pipeline against
    openapi/daloopa-api-openapi.yml (harvested verbatim from https://app.daloopa.com/swagger.json).
    Every statement below is grounded in Daloopa's own published documentation; nothing is invented.
  x-purpose: >-
    Non-destructive enhancements to the provider's spec. The original is never mutated. This overlay adds
    the runtime semantics the published spec omits — the global security requirement, the rate-limit
    contract, the deprecation/versioning posture, external documentation links, and the operation-level
    caveats an integrator or agent must know but cannot read from the spec.
extends: ../openapi/daloopa-api-openapi.yml

actions:

  # ---- Global security requirement -------------------------------------------------
  # The spec declares an apiKeyAuth securityScheme but never applies it at the document
  # root, so a naive reader could conclude the API is anonymous. Every operation requires it.
  - target: $
    description: Apply the declared Basic auth scheme globally — the spec defines it but never requires it.
    update:
      security:
        - apiKeyAuth: []

  # ---- Provenance + external documentation -----------------------------------------
  - target: $.info
    description: Record harvest provenance and correct the version label to the served major version.
    update:
      x-api-evangelist:
        harvested_from: https://app.daloopa.com/swagger.json
        harvested_on: '2026-08-11'
        harvest_http_status: 200
        harvest_content_type: application/vnd.oai.openapi
        spec_publicly_readable: true
        note: >-
          The spec is served unauthenticated at the API host root even though every operation is
          credentialed. The docs host (docs.daloopa.com/openapi.json) returns an HTML SPA shell with a 404 —
          the real contract is only at the API host.
      x-served-version: v3
      x-version-note: >-
        info.version reads "2.0.0" while the served base path is /api/v3/ and the release notes describe v3.
        The spec's own version string lags the API it describes.

  - target: $
    description: Add external documentation and a tag-level description block.
    update:
      externalDocs:
        description: Daloopa API documentation
        url: https://docs.daloopa.com/docs/overview

  # ---- Cross-cutting runtime semantics ---------------------------------------------
  - target: $.info
    description: Attach the published rate-limit, versioning and error contract that the spec omits.
    update:
      x-rate-limits:
        limit: 120
        window: minute
        scope: account
        status_on_exhaustion: 429
        response_headers_published: false
        retry_after_header: null
        backoff: exponential with jitter (docs suggest 1s, 2s, 4s, 8s)
        docs: https://docs.daloopa.com/docs/rate-limits
        note: >-
          429 is declared on 36 of 41 operations but no RateLimit-* or Retry-After header is declared
          anywhere. Backoff must be computed entirely client-side.
      x-quota:
        unit: datapoints
        period: monthly
        readable_at_runtime: true
        operations: [get_datapoint_consumption, get_series_consumption]
        note: >-
          Distinct from the request rate limit. This is the quota that actually gates usage on a metered
          contract, and unlike the rate limit it IS machine-readable.
        docs: https://docs.daloopa.com/docs/checking-consumption
      x-versioning:
        scheme: path-based major version
        current: v3
        previous: v2
        previous_status: deprecated, sunset date unpublished
        sunset_header: false
        deprecation_header: false
        migration_guide: https://docs.daloopa.com/docs/daloopa-api-v3-release-notes-migration-guide
      x-error-format:
        rfc9457: false
        content_type: application/json
        distinct_envelope_shapes: 7
        dominant_shape: '{detail: string}'
        note: >-
          Error envelopes vary by handler, not by status code. A client cannot write one error parser.
        detail: errors/daloopa-problem-types.yml
      x-idempotency:
        supported: false
        note: >-
          No Idempotency-Key mechanism. POST /api/v3/webhooks and POST /api/v3/partnerships/user are
          non-idempotent creates.
      x-pagination:
        style: limit/offset
        params: [limit, offset]
        response_envelope: [count, next, previous, results]
      x-periods:
        canonical_format: YYYYQN
        calendar_and_fiscal: both, mutually exclusive
        note: >-
          fiscal_* parameters are translated to the company's calendar quarters before filtering. Document
          responses carry both calendar_quarter and fiscal_quarter.
        docs: https://docs.daloopa.com/docs/period-format-standards

  # ---- Operation-level caveats an integrator cannot read from the spec -------------
  - target: $.paths['/api/v3/companies/fundamentals/series'].get
    description: Record the silent-omission behavior of the batch series lookup.
    update:
      x-batch-limit: 100
      x-silent-omission: true
      x-integration-note: >-
        Fundamental IDs not in the dataset visible to the caller are SILENTLY OMITTED from the response
        rather than erroring. Submitting 100 IDs and receiving 60 produces no signal about the other 40 —
        reconcile requested against returned IDs yourself.

  - target: $.paths['/api/v3/documents/{document_id}/content'].get
    description: Record the truncation cap, allowlist and transcript exclusion.
    update:
      x-max-characters: 100000
      x-truncation-flag: truncated
      x-bypass-param: full_content
      x-filing-type-allowlist: ['10-K', '10-Q', '8-K', 'News Article', 'Others']
      x-transcript-exclusion: >-
        Earnings call transcripts are excluded from whole-document access and return 403 by design. Use
        POST /api/v3/documents/keyword-search to query transcript content. This 403 is NOT retryable.
      x-recoverable-error: >-
        An unknown section name returns 400 carrying available_sections, so a caller can self-correct
        rather than fail. Read that array on 400 before giving up.

  - target: $.paths['/api/v3/documents/{document_id}/metadata'].get
    description: Highlight the agent-facing recommended_call hint.
    update:
      x-agent-affordance: >-
        Returns a recommended_call hint indicating whether to fetch the whole document or a specific
        section next, plus per-section character counts. This is the intended way to keep a 10-K inside an
        agent's context window. Unsupported filing types return 200 with recommended_call=not_supported and
        a populated reason rather than an error.

  - target: $.paths['/api/v3/export/{ticker}'].get
    description: Record the v3 default format change.
    update:
      x-default-format: parquet
      x-breaking-change-v3: >-
        Returns Parquet by default as of v3; v2 returned CSV. Pass output_format=csv to retain the old
        behavior.

  - target: $.paths['/api/v3/companies/bulk-subscribe'].post
    description: Record the partial-success pattern that returns 200.
    update:
      x-partial-success: true
      x-integration-note: >-
        When the requested company count exceeds the account's remaining subscription slots, this returns
        200 and processes only the first N that fit; the remainder are returned in skipped_limit_exceeded.
        A client that checks only the status code will silently under-subscribe.

  - target: $.paths['/api/v3/companies/status'].post
    description: Mark the freshness/cache-invalidation primitive.
    update:
      x-purpose: cache-invalidation
      x-integration-note: >-
        The documented way to decide whether cached values are stale. Compare latest_datapoint_updated_at
        against your last pull. The push equivalent is the webhook surface.
      x-see-also: asyncapi/daloopa-webhooks.yml

  - target: $.paths['/api/v3/investing-skills'].get
    description: Cross-link the skill catalog to its other two delivery channels.
    update:
      x-also-exposed-via:
        mcp_tools: [list_skills, get_skill]
        open_source: https://github.com/daloopa/daloopa-plugin-claude
      x-note: >-
        The same skill catalog is served over REST, over MCP, and published as 21 Apache-2.0 SKILL.md files.

  # ---- Agent-readiness summary ------------------------------------------------------
  - target: $.info
    description: Attach the agent-surface summary for this provider.
    update:
      x-agent-readiness:
        mcp_server: https://mcp.daloopa.com/server/mcp
        mcp_tools: 9
        mcp_write_capable: false
        mcp_auth: OAuth 2.1 with dynamic client registration and PKCE S256
        llms_txt: https://docs.daloopa.com/llms.txt
        agent_skills_published: 21
        agent_card: null
        crosswalk: mcp/daloopa-tool-crosswalk.yml
        note: >-
          All 9 MCP tools bind to real public REST operations and none of the 15 write operations are
          exposed to agents. The agent surface is a deliberate read-only projection of the REST API.