Alphanume Regulatory API

openapi: 3.2.0
info:
  contact:
    url: https://alphanume.com
  description: 'Point-in-time, survivorship-aware datasets for US equities and options research. Every response is JSON: {"count": N, "data": [...]} (paginated endpoints add has_more and next_cursor). Dates are always YYYY-MM-DD. Access: every dataset requires an Alphanume Pro API key (the Free plan is retired as of September 6, 2026). A 403 error with code PRO_SUBSCRIPTION_REQUIRED or DATE_RANGE_RESTRICTED means the key''s plan does not cover the request -- it does not mean the data is missing. Authentication: send your API key in the X-API-Key header (or Authorization: Bearer). Rate limit: 600 requests/minute. Keys come with a Pro subscription at https://alphanume.com/pricing. The same datasets are available as MCP tools at https://mcp.alphanume.com/mcp.'
  title: Alphanume Regulatory API
  version: 1.1.0
servers:
- url: https://api.alphanume.com
security:
- ApiKeyHeader: []
- BearerKey: []
tags:
- name: Regulatory
paths:
  /v1/regulatory/cyber-incidents:
    get:
      description: 'Material cybersecurity incidents: every Form 8-K filed under Item 1.05 (the SEC

        cyber-disclosure rule, live since 2023-12-18) plus its 8-K/A amendments -- the

        entire population, ~80 filings and growing. One row per filing, with FOUR distinct

        date roles kept rigorously separate: incident discovered, materiality determined

        (both extracted from prose, with day/month/quarter precision enums), disclosed and

        amended (both structural EDGAR dates, never model-guessed) -- plus the intervals

        between them (investigation time, compliance-clock time, total latency).


        Flags are three-state: 1 = filing says yes, 0 = filing says no, NULL = filing does

        not say -- never collapsed. Amendments are separate rows linked to their original

        (original_accession_number, days_original_to_amendment); an incident with three

        8-K/As is four rows. materiality_determined_date is sparse (~15% fill) because

        most filings simply do not state one. days_determination_to_disclosure is CALENDAR

        days; the SEC''s deadline is four BUSINESS days -- adjust before compliance claims.


        Requires an Alphanume Pro API key. A 403 PRO_SUBSCRIPTION_REQUIRED or

        DATE_RANGE_RESTRICTED error means the key''s plan does not cover the request --

        it does not mean the data is missing.'
      operationId: get_cyber_incidents
      parameters:
      - description: Ticker symbol filter, e.g. 'AAPL'. Case-insensitive.
        in: query
        name: ticker
        required: false
        schema:
          type: string
      - description: SEC CIK number (digits only) -- the durable issuer key (3 rows have no ticker).
        in: query
        name: cik
        required: false
        schema:
          type: string
      - description: 1 = 8-K/A amendments only, 0 = original 8-Ks only.
        in: query
        name: is_amendment
        required: false
        schema:
          type: string
      - description: One of data-breach, unauthorized-access, ransomware, business-email-compromise, other, unstated.
        in: query
        name: attack_type
        required: false
        schema:
          type: string
      - description: 1 = originals that were later amended, 0 = originals never amended (NULL on amendment rows themselves).
        in: query
        name: amended_flag
        required: false
        schema:
          type: string
      - description: '1/0 three-state flag: filing states data was/was not stolen (unfiltered rows include NULL = filing does not say).'
        in: query
        name: data_compromised_flag
        required: false
        schema:
          type: string
      - description: '1/0 three-state flag: filing states operations were/were not disrupted.'
        in: query
        name: operations_disrupted_flag
        required: false
        schema:
          type: string
      - description: '1/0 three-state flag: incident originated at a vendor/third party.'
        in: query
        name: third_party_incident_flag
        required: false
        schema:
          type: string
      - description: '1/0: rows where the labeler declined the filing text (served with NULL extraction fields; the disclosure event is still real).'
        in: query
        name: refused
        required: false
        schema:
          type: string
      - description: Exact date, YYYY-MM-DD. Cannot be combined with the date range parameters.
        in: query
        name: date
        required: false
        schema:
          type: string
      - description: Start of date range, inclusive (YYYY-MM-DD).
        in: query
        name: date_gte
        required: false
        schema:
          type: string
      - description: End of date range, inclusive (YYYY-MM-DD).
        in: query
        name: date_lte
        required: false
        schema:
          type: string
      - description: Start of date range, exclusive (YYYY-MM-DD).
        in: query
        name: date_gt
        required: false
        schema:
          type: string
      - description: End of date range, exclusive (YYYY-MM-DD).
        in: query
        name: date_lt
        required: false
        schema:
          type: string
      - description: YYYY-MM-DD, on last_updated -- rows touched by the amendment-linkage sweep since this date.
        in: query
        name: updated_since
        required: false
        schema:
          type: string
      - description: 'Pagination: ''date'' from next_cursor (send with cursor_accession).'
        in: query
        name: cursor_date
        required: false
        schema:
          type: string
      - description: 'Pagination: ''accession_number'' from next_cursor (send with cursor_date).'
        in: query
        name: cursor_accession
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvelope'
          description: Matching rows.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      summary: 'Material cybersecurity incidents: every Form 8-K filed under Item 1.05 (the SEC'
      tags:
      - Regulatory
components:
  responses:
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: 'PRO_SUBSCRIPTION_REQUIRED: the key''s plan does not include API access; every endpoint requires an active Pro subscription. DATE_RANGE_RESTRICTED: a legacy free-tier key asked for dates outside its window. In both cases the data is not missing.'
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Missing or unrecognized API key.
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Invalid or conflicting query parameters.
    RateLimited:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Rate limit exceeded (600/min); the body carries retry_after_seconds.
  schemas:
    PaginatedEnvelope:
      properties:
        count:
          type: integer
        data:
          items:
            type: object
          type: array
        has_more:
          type: boolean
        next_cursor:
          description: 'Keyset cursor: pass its fields back as the cursor_* query parameters to fetch the next page.'
          type:
          - object
          - 'null'
      required:
      - count
      - data
      - has_more
      - next_cursor
      type: object
    Error:
      additionalProperties: true
      properties:
        error: {}
      type: object
  securitySchemes:
    ApiKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey
    BearerKey:
      scheme: bearer
      type: http
externalDocs:
  description: MCP server exposing these datasets as tools (OAuth or X-API-Key).
  url: https://mcp.alphanume.com/mcp