Nordic Financial News Exchanges API

openapi: 3.2.0
info:
  title: Nordic Financial News Exchanges API
  version: v1.0
  description: 'REST API for Nordic financial news. Each article is summarized in English (headline, short summary, and key points) with the original-language article linked via `article_url`. The full article body stays at the source. ## Authentication

    All endpoints require Bearer token authentication using an API key. Include the API key in the Authorization header:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    ## Rate Limiting

    Rate limits apply per account, shared across every API key on that account — not per

    individual key:

    - **Free**: 100 requests/hour

    - **Plus**: 100 requests/hour

    - **Pro**: 5,000 requests/hour


    On Free and Plus, MCP tool calls have their own hourly and monthly allowance and do not

    count toward these REST limits. On Pro, REST requests and MCP tool calls share one allowance. Rate limit information is included in response headers:

    - `X-RateLimit-Limit`: Maximum requests per hour

    - `X-RateLimit-Remaining`: Requests remaining

    - `X-RateLimit-Reset`: Seconds until limit resets

    - `X-RateLimit-Policy`: Human-readable rate limit policy (e.g. `5000 per hour; fixed window`)


    A single client IP is additionally capped at 300 requests per 5-minute window, so

    reaching your account''s full hourly allowance requires spreading requests across more

    than one source IP. The `/health` endpoint is exempt from rate limiting and does not return rate limit headers. ## Monthly Usage Limits

    Free and Plus accounts have a fixed monthly allowance that resets at the start of each

    calendar month, shared across every API key on the account:

    - **Free**: 100 requests/month

    - **Plus**: 100 requests/month


    Responses on these plans include:

    - `X-Monthly-Limit`: Maximum requests for the current month

    - `X-Monthly-Remaining`: Requests remaining this month

    - `X-Monthly-Reset`: ISO 8601 timestamp when the allowance resets


    When the allowance is exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header. Pro has no hard limit. It includes 25,000 requests per billing cycle, with usage-based

    pricing beyond that, so requests are never blocked. Responses on Pro include:

    - `X-Monthly-Usage`: Requests used in the current billing cycle

    - `X-Monthly-Reset`: ISO 8601 timestamp when the current billing cycle ends


    A Pro billing cycle follows your subscription''s billing period, which begins on the

    date you subscribed and is not necessarily a calendar month. Usage is counted by day,

    so the first day of a billing cycle is counted in full. ## Caching

    Every list and single-resource endpoint returns an `ETag`. Most also return

    `Last-Modified` (on lists, when the page is not empty); `GET /stories/{id}` and the

    Events endpoints do not. Send the ETag back as `If-None-Match`, or the date as

    `If-Modified-Since`, to receive `304 Not Modified` when nothing has changed. A 304

    has no body and does not count against the monthly request allowance. `GET /events`, `GET /events/{id}` and `GET /companies/{identifier}/events` return an

    `ETag` but no `Last-Modified`, so revalidate those routes with `If-None-Match`. An

    event''s visible company and story membership, and its live article count, all change

    without moving its `updated_at`, so a date-based validator would report "not

    modified" across a change the `ETag` catches. Some requests are never cached and return `Cache-Control: no-cache, no-store` with

    no `ETag`: full-text search (`q`), `updated_after` sync requests, and `GET /search`. The `ETag` reflects the response as served, not only record timestamps. On articles

    and stories, including the company-scoped routes, and on `GET /calendar_events`, it

    changes when a plan limit alters the visible set, and on stories when a story''s

    visible article set changes. A changed `ETag` does not necessarily mean a record was

    updated. On the Events endpoints the `ETag` additionally covers each event''s visible

    company and story ids and its live article count, none of which move the event''s

    `updated_at`. ## Pagination

    List endpoints support cursor-based pagination.'
  contact:
    name: API Support
    email: hello@nordicfinancialnews.com
servers:
- url: https://nordicfinancialnews.com
  description: Production server
tags:
- name: Exchanges
paths:
  /api/v1/exchanges:
    get:
      summary: List Exchanges
      tags:
      - Exchanges
      security:
      - bearer_auth: []
      description: Returns active Nordic stock exchanges, ordered alphabetically. Supports filtering by country.
      parameters:
      - name: limit
        in: query
        required: false
        description: Number of exchanges to return per page (default 25, max 100).
        example: 25
        schema:
          type: integer
      - name: cursor
        in: query
        required: false
        description: Opaque pagination cursor from a previous response.
        schema:
          type: string
      - name: country
        in: query
        required: false
        description: Filter by country using ISO 3166-1 alpha-2 code. Comma-separated for multiple (e.g. `SE,NO`). Case-insensitive.
        example: SE
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: 'Comma-separated list of fields to include in the response. Available fields: `id`, `name`, `mic_code`, `acronym`, `country`.'
        example: id,name,mic_code
        schema:
          type: string
      - name: If-None-Match
        in: header
        required: false
        description: ETag value from a previous response. Returns `304 Not Modified` if data has not changed.
        schema:
          type: string
      - name: If-Modified-Since
        in: header
        required: false
        description: HTTP date from a previous `Last-Modified` header. Returns `304 Not Modified` if nothing has changed since.
        schema:
          type: string
      responses:
        '200':
          description: Exchanges retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  exchanges:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExchangeSummary'
                  pagination:
                    type: object
                    properties:
                      count:
                        type: integer
                      next_cursor:
                        type:
                        - string
                        - 'null'
        '304':
          description: Not Modified
        '401':
          description: unauthorized
          content:
            application/json:
              examples:
                unauthorized:
                  value:
                    type: https://docs.nordicfinancialnews.com/problems/auth-invalid
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid API key
                    instance: urn:request:abc123
              schema:
                $ref: '#/components/schemas/problem_details'
        '403':
          description: forbidden - insufficient scope
          content:
            application/json:
              examples:
                forbidden:
                  value:
                    type: https://docs.nordicfinancialnews.com/problems/auth-insufficient
                    title: Forbidden
                    status: 403
                    detail: Insufficient scope for this resource
                    instance: urn:request:abc123
              schema:
                $ref: '#/components/schemas/problem_details'
      operationId: getApiV1Exchanges
      x-operation-id-source: derived
  /api/v1/exchanges/{identifier}:
    parameters:
    - name: identifier
      in: path
      required: true
      description: Exchange ID or MIC code (e.g. `XSTO`)
      schema:
        type: string
    get:
      summary: Get Exchange Details
      tags:
      - Exchanges
      security:
      - bearer_auth: []
      description: Returns detailed information about a stock exchange, including currency, timezone, and location. Look up by exchange ID (e.g. `exch_nasdaq1`) or MIC code (e.g. `XSTO`).
      parameters:
      - name: If-None-Match
        in: header
        required: false
        description: ETag value from a previous response. Returns `304 Not Modified` if data has not changed.
        schema:
          type: string
      - name: If-Modified-Since
        in: header
        required: false
        description: HTTP date from a previous `Last-Modified` header. Returns `304 Not Modified` if nothing has changed since.
        schema:
          type: string
      responses:
        '200':
          description: Exchange retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  exchange:
                    $ref: '#/components/schemas/ExchangeDetail'
                required:
                - exchange
        '304':
          description: Not Modified
        '404':
          description: Exchange not found
          content:
            application/json:
              examples:
                not_found:
                  value:
                    type: https://docs.nordicfinancialnews.com/problems/not-found
                    title: Not Found
                    status: 404
                    detail: The requested resource could not be found
                    instance: urn:request:abc123
              schema:
                $ref: '#/components/schemas/problem_details'
      operationId: getApiV1ExchangesByIdentifier
      x-operation-id-source: derived
  /api/v1/exchanges/{identifier}/companies:
    parameters:
    - name: identifier
      in: path
      required: true
      description: Exchange ID or MIC code (e.g. `XSTO`)
      schema:
        type: string
    get:
      summary: List Exchange Companies
      tags:
      - Exchanges
      security:
      - bearer_auth: []
      description: Returns companies listed on a specific exchange, ordered alphabetically. The `ticker` and `exchange` shown for each company reflect its primary listing, which may be on a different exchange if the company is listed on multiple exchanges.
      parameters:
      - name: limit
        in: query
        required: false
        description: Number of companies to return per page (default 25, max 100).
        example: 25
        schema:
          type: integer
      - name: cursor
        in: query
        required: false
        description: Opaque pagination cursor from a previous response.
        schema:
          type: string
      - name: If-None-Match
        in: header
        required: false
        description: ETag value from a previous response. Returns `304 Not Modified` if data has not changed.
        schema:
          type: string
      - name: If-Modified-Since
        in: header
        required: false
        description: HTTP date from a previous `Last-Modified` header. Returns `304 Not Modified` if nothing has changed since.
        schema:
          type: string
      responses:
        '200':
          description: Exchange companies retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  companies:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompanySummary'
                  pagination:
                    type: object
                    properties:
                      count:
                        type: integer
                      next_cursor:
                        type:
                        - string
                        - 'null'
                required:
                - companies
        '304':
          description: Not Modified
        '404':
          description: Exchange not found
          content:
            application/json:
              examples:
                not_found:
                  value:
                    type: https://docs.nordicfinancialnews.com/problems/not-found
                    title: Not Found
                    status: 404
                    detail: The requested resource could not be found
                    instance: urn:request:abc123
              schema:
                $ref: '#/components/schemas/problem_details'
      operationId: getApiV1ExchangesByIdentifierCompanies
      x-operation-id-source: derived
components:
  schemas:
    ExchangeDetail:
      allOf:
      - $ref: '#/components/schemas/ExchangeSummary'
      - type: object
        properties:
          operating_mic_code:
            type:
            - string
            - 'null'
            description: Parent operating MIC code (for segment exchanges)
            example: XSTO
          currency:
            type:
            - string
            - 'null'
            description: Primary trading currency (ISO 4217)
            example: SEK
          ticker_suffix:
            type:
            - string
            - 'null'
            description: Ticker suffix used for this exchange
            example: ST
          timezone:
            type:
            - string
            - 'null'
            description: Exchange timezone
            example: Europe/Stockholm
          city:
            type:
            - string
            - 'null'
            description: City where the exchange is located
          indices:
            type: array
            description: Stock indices on this exchange
            items:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                symbol:
                  type: string
    CompanySummary:
      type: object
      required:
      - id
      - name
      - slug
      - former_tickers
      - also_listed_on
      properties:
        id:
          type: string
          description: Unique company identifier
          example: w55fcw3pbg3p
        name:
          type: string
          description: Company name
          example: Volvo Car AB
        slug:
          type: string
          description: URL-friendly company name
          example: VOLCAR-B
        ticker:
          type:
          - string
          - 'null'
          description: Primary stock ticker (null if unlisted)
          example: VOLCAR-B
        former_tickers:
          type: array
          items:
            type: string
          description: Tickers the company was formerly listed under, from delisted or renamed listings, excluding any that are still a current ticker. Always present; empty when none. The ticker filter resolves former tickers as well as the current one, so a match on an old ticker still returns the company; this field tells you the ticker you searched by is historical.
          example:
          - VOLV
        is_active:
          type: boolean
          description: Whether the company is currently active/operating
          example: true
        exchange:
          type:
          - object
          - 'null'
          description: Primary exchange where the company is listed
          properties:
            id:
              type: string
              description: Exchange identifier
            name:
              type: string
              description: Exchange display name
            mic_code:
              type: string
              description: ISO 10383 Market Identifier Code
        also_listed_on:
          type: array
          description: 'The company''s other active listings, excluding the primary listing above: cross-listings on other exchanges and additional share classes (which may be on the same exchange). Always present; empty when the company is single-listed or unlisted. The row''s ticker/exchange fields are the primary listing only. Company detail stock_listings is the authoritative full set.'
          items:
            type: object
            required:
            - ticker
            - mic_code
            properties:
              ticker:
                type: string
                description: Ticker on this secondary exchange
                example: VOLCAR-B
              mic_code:
                type: string
                description: ISO 10383 Market Identifier Code of this exchange
                example: XSTO
          example: []
    ExchangeSummary:
      type: object
      required:
      - id
      - name
      - mic_code
      properties:
        id:
          type: string
          description: Unique exchange identifier
          example: exch_nasdaq1
        name:
          type: string
          description: Exchange display name
          example: Nasdaq Stockholm
        mic_code:
          type: string
          description: ISO 10383 Market Identifier Code
          example: XSTO
        acronym:
          type:
          - string
          - 'null'
          description: Exchange acronym
          example: NASDAQ
        country:
          type: object
          description: Country where the exchange is located
          properties:
            id:
              type: string
            name:
              type: string
            iso2_code:
              type: string
    problem_details:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - instance
      properties:
        type:
          type: string
          description: URI that identifies the problem type
        title:
          type: string
          description: Short human-readable summary
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable explanation
        instance:
          type: string
          description: URI that identifies the specific occurrence
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API Key authentication using Bearer token