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.