algoum-de Events API

openapi: 3.2.0
info:
  title: Algoum De Events API
  version: 1.0.0
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
  description: 'Operations tagged events across 3 of this provider''s published API definitions: algoum-de-api-openapi.json, algoum-de-site-openapi.json, algoum-de-site-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.algoum.de/v1
  name: production
  description: Production environment.
security:
- bearerAuth: []
tags:
- name: Events
  summary: Material events (Form 8-K)
  description: 'Material events a company has to disclose – leadership changes, mergers,

    bankruptcies, cyber incidents and more. Available as searchable history,

    as a cross-market feed and as a push stream.'
paths:
  /events:
    get:
      tags:
      - Events
      operationId: listEvents
      summary: Search material events
      description: 'Searches the REST history of material events.

        Fixed sort order: `filed_at` descending, then `id` descending.


        Either `ticker` or `cik` is required; a request without both is

        answered with `400`. An unrestricted query would have to scan the

        whole history.


        `ticker` matches the symbol at the time of the filing (see `Event`).

        For the full history of a company that changed its ticker, filter by

        `cik` instead.'
      parameters:
      - $ref: '#/components/parameters/Ticker'
      - $ref: '#/components/parameters/Cik'
      - name: event_type
        in: query
        description: Filter on a taxonomy type.
        schema:
          $ref: '#/components/schemas/EventType'
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: List of material events.
          content:
            application/json:
              examples:
                default:
                  $ref: '#/components/examples/EventList'
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Event'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: https://api.algoum.de/v1
      name: production
      description: Production environment.
  /events/recent:
    get:
      tags:
      - Events
      operationId: listRecentEvents
      summary: Most recently filed events (minute window)
      description: 'Returns the material events filed in the last `minutes` minutes across

        all companies – no ticker/CIK required. Filters on the filing time

        (`filed_at`).

        Fixed sort order: `filed_at` descending, then `id` descending.'
      parameters:
      - name: minutes
        in: query
        description: Look-back window in minutes (capped at 10080 = 7 days).
        schema:
          type: integer
          minimum: 1
          maximum: 10080
          default: 15
      - $ref: '#/components/parameters/Ticker'
      - $ref: '#/components/parameters/Cik'
      - name: event_type
        in: query
        description: Filter on a taxonomy type.
        schema:
          $ref: '#/components/schemas/EventType'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Most recently filed material events.
          content:
            application/json:
              examples:
                default:
                  $ref: '#/components/examples/EventList'
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Event'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: https://api.algoum.de/v1
      name: production
      description: Production environment.
  /events/{id}:
    get:
      tags:
      - Events
      operationId: getEvent
      summary: Get a single event
      description: Returns a single event including item code and source document.
      parameters:
      - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: A single material event.
          content:
            application/json:
              examples:
                default:
                  $ref: '#/components/examples/EventItem'
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: https://api.algoum.de/v1
      name: production
      description: Production environment.
  /events/stream:
    get:
      tags:
      - Events
      operationId: streamEvents
      summary: SSE stream of new events
      description: 'Server-Sent-Events stream. The client connects once and has new events

        pushed to it as soon as they are processed. Every message uses the event

        name `event` and carries one serialised event object as JSON in its

        `data` field. Every 30 seconds without traffic the server sends the SSE

        comment `: keepalive`, so a dead connection is noticed.


        Observed latency from filing at the SEC to delivery: median 39.8 seconds

        over 14 days of live operation, about 18 seconds of which pass at the

        SEC itself (from acceptance to visibility in its feed). This is a push

        within seconds, not within milliseconds, and it is an observation rather

        than a guaranteed figure.


        Messages carry no ID, so a reconnect does not replay what was missed.

        After a connection drop, catch up through `/events/recent` and then keep

        listening. The stream guide walks through a complete client.'
      externalDocs:
        description: Streaming guide – reconnect, catching up, example client.
        url: https://www.algoum.de/docs/streaming
      parameters:
      - $ref: '#/components/parameters/Ticker'
      - name: event_type
        in: query
        description: Stream only events of this type.
        schema:
          $ref: '#/components/schemas/EventType'
      responses:
        '200':
          description: Continuous event stream.
          content:
            text/event-stream:
              itemSchema:
                $ref: '#/components/schemas/Event'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    servers:
    - url: https://api.algoum.de/v1
      name: production
      description: Production environment.
components:
  parameters:
    PathId:
      name: id
      in: path
      required: true
      description: Resource ID.
      schema:
        type: string
    From:
      name: from
      in: query
      description: First day of the window (`YYYY-MM-DD`), inclusive. Filtering happens on a pure date field; of an RFC 3339 value only the calendar day counts.
      schema:
        type: string
        format: date
    Ticker:
      name: ticker
      in: query
      description: Stock ticker (preferred instrument filter), e.g. `AAPL`.
      schema:
        type: string
        example: AAPL
    To:
      name: to
      in: query
      description: Last day of the window (`YYYY-MM-DD`), inclusive. Filtering happens on a pure date field; of an RFC 3339 value only the calendar day counts.
      schema:
        type: string
        format: date
    Limit:
      name: limit
      in: query
      description: Maximum number of results.
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
    Cursor:
      name: cursor
      in: query
      description: Opaque cursor for the next page.
      schema:
        type: string
    Cik:
      name: cik
      in: query
      description: 'Central Index Key (alternative to the ticker). Leading zeros are optional: `0000320193` and `320193` return the same rows. In responses the key is always ten digits, so it is safe to use as a join key.'
      schema:
        type: string
        example: 0000320193
  schemas:
    Envelope:
      type: object
      description: Uniform response envelope. `data` is specialised per endpoint.
      required:
      - meta
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      description: Uniform metadata present in every response.
      required:
      - request_id
      - source
      properties:
        request_id:
          type: string
          example: req_01H...
        source:
          type: string
          example: sec_edgar
        data_freshness:
          type: string
          format: date-time
          description: Filing time of the most recently processed filing. Absent as long as no data has been imported – no freshness is claimed in that case.
          example: '2026-07-13T21:05:00-04:00'
        next_cursor:
          type:
          - string
          - 'null'
          description: Cursor for the next page; `null` at the end.
        warnings:
          type: array
          items:
            type: string
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          properties:
            code:
              type: string
              example: invalid_parameter
            message:
              type: string
              example: Parameter 'ticker' or 'cik' is required.
            request_id:
              type: string
              example: req_01H...
    Event:
      type: object
      required:
      - ticker
      - cik
      - event_type
      - item_code
      - title
      - event_date
      - filed_at
      - filing_id
      - source_url
      properties:
        ticker:
          type: string
          description: Trading symbol of the common stock at the time of the filing, taken from the cover page of the 8-K. If the cover page does not tag one, the current symbol of the company is used. Empty if neither is known, e.g. for companies without listed stock or delisted since.
          example: XYZ
        cik:
          type: string
          example: '0001234567'
        event_type:
          $ref: '#/components/schemas/EventType'
        item_code:
          type: string
          example: '1.03'
        title:
          type: string
          example: Chapter 11 Bankruptcy Filing
        event_date:
          type: string
          format: date
          example: '2026-07-15'
        filed_at:
          type: string
          format: date-time
          example: '2026-07-15T13:42:00-04:00'
        filing_id:
          type: string
          example: fil_0001234567-26-000045
        source_url:
          type: string
          format: uri
    EventType:
      type: string
      description: Normalised event type. Every value is derived from a SEC item code and does actually occur in the data.
      enum:
      - bankruptcy
      - cyber_incident
      - leadership_change
      - delisting
      - earnings_release
      - merger_acquisition
      - capital_action
      - accounting_issue
      - auditor_change
      - late_filing
      - other_material_event
  responses:
    ServiceUnavailable:
      description: 'A prerequisite of the endpoint is not ready: the ticker universe is still loading, or the event stream is not running. Temporary – retrying later is worthwhile.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded. The rejection is issued at the edge, in front of the API, so it does not necessarily carry the JSON error envelope and has no `request_id`. Slow down and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Unexpected server-side error, error code `internal_error`. The message is always the same; the cause stays in the server log, keyed by the `request_id` that the response repeats. Quote it in a support request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  examples:
    EventList:
      summary: Two material events
      value:
        meta:
          request_id: req_01K4W83T2K5B
          source: sec_edgar
          data_freshness: '2026-07-15T13:42:00-04:00'
          next_cursor: eyJvIjo1MH0
          warnings: []
        data:
        - ticker: XYZ
          cik: '0001234567'
          event_type: bankruptcy
          item_code: '1.03'
          title: Chapter 11 Bankruptcy Filing
          event_date: '2026-07-15'
          filed_at: '2026-07-15T13:42:00-04:00'
          filing_id: 0001234567-26-000045
          source_url: https://www.sec.gov/Archives/edgar/data/1234567/000123456726000045/form8k.htm
        - ticker: XYZ
          cik: '0001234567'
          event_type: leadership_change
          item_code: '5.02'
          title: Departure of Chief Financial Officer
          event_date: '2026-07-02'
          filed_at: '2026-07-02T16:11:00-04:00'
          filing_id: 0001234567-26-000039
          source_url: https://www.sec.gov/Archives/edgar/data/1234567/000123456726000039/form8k.htm
    EventItem:
      summary: A single material event
      value:
        meta:
          request_id: req_01K4W84B8V3Q
          source: sec_edgar
          data_freshness: '2026-07-15T13:42:00-04:00'
          next_cursor: null
          warnings: []
        data:
          ticker: XYZ
          cik: '0001234567'
          event_type: bankruptcy
          item_code: '1.03'
          title: Chapter 11 Bankruptcy Filing
          event_date: '2026-07-15'
          filed_at: '2026-07-15T13:42:00-04:00'
          filing_id: 0001234567-26-000045
          source_url: https://www.sec.gov/Archives/edgar/data/1234567/000123456726000045/form8k.htm
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your own API key as a bearer token (`Authorization: Bearer <key>`).'
externalDocs:
  description: Guides – getting started, conventions, streaming.
  url: https://www.algoum.de/docs
x-refined-from:
- algoum-de-api-openapi.json
- algoum-de-site-openapi.json
- algoum-de-site-openapi.yaml