overlay: 1.0.0 info: title: API Evangelist enhancements for the MerQube API version: 1.0.0 extends: openapi/merqube-api-openapi.json x-provenance: generated: '2026-08-25' method: generated source: >- Authored by API Evangelist against MerQube's own published contract (https://api.merqube.com/api, OpenAPI 3.1, info.version 4.40.0). Every action below either encodes a fact MerQube states in prose but omits from the contract, or repairs a defect that is demonstrably present in the published document. Nothing here invents behaviour. The original specification is never mutated. actions: - target: $ description: >- Declare the API-key security scheme. MerQube's Authentication document specifies an Authorization header carrying "APIKEY {key}", but the published contract has no components.securitySchemes at all, so a generated client has no way to authenticate. update: components: securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: >- MerQube API key. Send as `Authorization: APIKEY {your_api_key}` - note the literal "APIKEY " prefix, not "Bearer". Keys are issued by support@merqube.com after registering at https://merqube.com/register. Requests without a key are accepted and resolve to the world-readable `default` namespace only. Source: https://merqube.stoplight.io/docs/api/p6s6m4p35ehfv-authentication - target: $ description: >- Apply the scheme as an OPTIONAL default. An empty requirement object is included first because MerQube genuinely serves anonymous callers - dropping it would misrepresent the public read surface as gated. update: security: - {} - apiKeyAuth: [] - target: $.components.schemas.CountryCode description: >- Repair a YAML 1.1 boolean coercion defect. The published enum contains a JSON `false` where the ISO 3166-1 alpha-2 code for Norway, "NO", belongs - the source YAML at https://api.merqube.com/api-raw writes it unquoted. As published, Norway is unrepresentable and every generated client emits a boolean enum member. This overlay restores "NO"; the fix in MerQube's source is simply to quote it. update: enum: - AE - AR - AT - AU - BD - BE - BG - BH - BR - BW - CA - CH - CI - CL - CN - CO - CY - CZ - DE - DK - EC - EG - ES - FI - FR - GB - GR - HK - HR - HU - ID - IE - IL - IN - IS - IT - JP - KH - KR - KW - LK - LU - MX - MY - NL - 'NO' - NZ - PE - PH - PK - PL - PT - QA - RU - SA - SE - SG - SI - SK - TH - TN - TR - TT - TW - US - VN - ZA - ZM x-api-evangelist-note: >- Only the boolean `false` member is replaced with the string "NO"; every other member is reproduced verbatim from the published enum. - target: $.info description: >- Record the canonical, machine-readable locations of this contract, which MerQube states in its SDK Overview but not in the document itself. update: x-spec-locations: resolved: https://api.merqube.com/api raw: https://api.merqube.com/api-raw rendered: https://www.merqube.com/api docs: https://merqube.stoplight.io/ x-support-contact: support@merqube.com - target: $.info description: >- Document the response envelope, which is uniform across the API but described nowhere. update: x-response-envelope: results: array of the requested resource error_codes: >- array of {code, message} carrying PARTIAL failures on an HTTP 200 - e.g. code "00001" message "RESULTS_WERE_FILTERED" when namespace permissions withheld rows deprecation_warnings: array reserved for in-band deprecation notices; observed empty linked_resources: object of related resource references x-observed: '2026-08-25 on GET https://api.merqube.com/index' - target: $.info description: >- Encode the concurrency contract. MerQube's SDK Overview states the `status` block must be sent on PUT/PATCH and the write is rejected unless it matches storage - a compare-and-set that no reader of the OpenAPI alone would discover. update: x-concurrency: mechanism: compare-and-set token_field: status required_on: - PUT - PATCH on_mismatch: write rejected idempotency_key_header: null duplicate_create: HTTP 409 on a duplicate (name, namespace) lock_field: status.locked_after source: https://github.com/merqube/merqube-client-lib/blob/main/docs/Overview.md - target: $.info description: >- Encode the authorization model - namespaces, not scopes - so an agent can reason about why a result set is short. update: x-authorization-model: primitive: namespace public_namespace: default anonymous_access: true scopes: none partial_filtering_signal: error_codes[].code == "00001" grant_process: request namespace access from support@merqube.com - target: $.servers description: >- Note that the staging host named in MerQube's Stoplight-hosted copy of this spec (staging.api.merqube.com) is stale; the live document names api.staging.merqube.com, which responds. Recorded so a reader of the docs portal is not sent to a dead host. update: - url: https://api.merqube.com description: Production server x-verified: '2026-08-25 - GET /api returned 200' - url: https://api.staging.merqube.com description: Testing server for next generation features x-verified: '2026-08-25 - GET /api returned 200 with the same document' x-superseded-alias: https://staging.api.merqube.com - target: $ description: >- Flag the two path keys published without a leading slash. They are invalid against the OpenAPI path-templating rules and they are why MerQube's own Stoplight Prism mock refuses to start (422 UNPROCESSABLE_ENTITY, "Malformed path 'index/{uuid}/identifier/{provider}'"). The repair is to rename each key with a leading "/"; that is a key rename rather than a value patch, so it is recorded here as a finding rather than applied. update: x-api-evangelist-findings: malformed_path_keys: - index/{uuid}/identifier/{provider} - index/{uuid}/identifier/{provider}/{identifier_name} impact: >- Breaks the hosted mock at https://stoplight.io/mocks/merqube/api/445185098 and any strict OpenAPI 3.1 validator. fix: prefix each key with "/" x-observed: '2026-08-25' - target: $ description: >- Declare the tags MerQube uses on operations but does not define, so a rendered reference groups correctly instead of dropping operations into an untitled bucket. update: tags: - name: index description: Index manifests, their portfolios, documents, data collections and run state. - name: identifier description: >- Vendor dissemination tickers binding an index to Bloomberg, Reuters, Morningstar, FactSet, Nasdaq or Wind. - name: security description: SecAPI - security metrics, levels and statistics. - name: security_list description: Named, permissioned collections of securities. - name: portfolio_handler description: Target-portfolio selection, validation, locking and dissemination policy. - name: options description: Listed-option pricing, strike solving and availability. - name: legacy_equity_security description: >- Superseded equity metric endpoints under /security/equity_legacy/. Named "legacy" by MerQube but not marked deprecated and carrying no sunset date. - name: helper description: >- Server-side index templating and solvers. These render a complete index manifest WITHOUT creating it - the closest thing this API has to a dry-run. - name: api description: Self-description - GET /api returns this OpenAPI document.