Alphanume Corporate Actions 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 Corporate Actions API
  version: 1.1.0
servers:
- url: https://api.alphanume.com
security:
- ApiKeyHeader: []
- BearerKey: []
tags:
- name: Corporate Actions
paths:
  /v1/corporate-actions/spinoffs:
    get:
      description: 'Spin-off calendar: US spin-offs registered on Form 10 since 2015 -- the new

        company''s ticker, the parent''s ticker before and after, the distribution ratio,

        record and distribution dates, and the first regular-way trading day of the new

        shares, each key value stamped with the time it first became public on EDGAR.


        Built for the spin-off pair trade (e.g. long the parent, short the spun-off

        company) and for point-in-time backtests. One row per spin-off; spin_id is the

        spun-off company''s SEC CIK. `date` filters apply to first_trade_date.


        first_trade_date is the first REGULAR-WAY session of the new shares. first_trade_basis

        says how firm it is: ''stated'' (a filing gives the date), ''estimated'' (the session after

        the distribution date -- about a third of spin-offs instead start trading ON the

        distribution date), ''confirmed'' (the first daily bar actually printed).

        first_trade_confirmed_at is the UTC time the live pipeline first saw it trade (NULL for

        history loaded before launch). ratio = new shares per ONE parent share as the filing

        states it (0.5 = one for every two; before any reverse split the parent does at the spin).

        when_issued_date and child_wi_symbol / parent_wi_symbol describe the when-issued lines

        (lowercase ''w'' symbols such as MSGRw), which trade thinly in the days before regular-way.


        parent_listing says whether parent_ticker is a US line verified to trade before the spin

        (''us_listed''), or why there is none: ''foreign_only'' (see parent_home_ticker, e.g. a Tel

        Aviv or Johannesburg listing), ''not_listed'' (e.g. a non-traded REIT).


        Point-in-time: registered_at (Form 10 first public), child_ticker_first_seen_at,

        ratio_first_seen_at and trade_date_first_seen_at are EDGAR acceptance times (UTC) of the

        first filing that stated the value now served. A press release can lead EDGAR by a few

        days. Confidential draft filings are never used.


        Scope and limits: spin-offs registered on Form 10 / Form 20-F only (about 97% of spin-offs

        that created a new ticker since 2016); split-offs and separations registered on S-1/S-4

        (e.g. tracking-stock reorganizations) are not covered. About 1 spin-off in 7 has no

        trading date until it trades.


        Default order: the forward calendar first (registered / scheduled, nearest expected first

        trade first), then everything else, most recent first trade first.


        Requires an Alphanume Pro API key. There is no date clamp on this route.'
      operationId: get_spinoffs
      parameters:
      - 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: 'Comma-separated statuses: registered (Form 10 public, no trade date yet), scheduled (a first trade date is stated or estimated), completed (the new shares traded regular-way), withdrawn, inactive (no trade 10+ days past the expected date, or no filing for 18 months); or the shorthands ''all'' (default) and ''upcoming'' (registered + scheduled).'
        in: query
        name: status
        required: false
        schema:
          type: string
      - description: Symbol matched against the spun-off company (child_ticker), the parent before the spin (parent_ticker) and the parent after it (parent_ticker_after), so any side works.
        in: query
        name: ticker
        required: false
        schema:
          type: string
      - description: Only rows updated at or after this date/datetime (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS) -- for incremental syncs.
        in: query
        name: updated_since
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Matching rows.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ProSubscriptionRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
      summary: 'Spin-off calendar: US spin-offs registered on Form 10 since 2015 -- the new'
      tags:
      - Corporate Actions
components:
  responses:
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Missing or unrecognized API key.
    ProSubscriptionRequired:
      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), or this Pro-only dataset is not covered by the key. No choice of dates makes the request succeed. The data is not missing.'
    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:
    Envelope:
      properties:
        count:
          type: integer
        data:
          items:
            type: object
          type: array
      required:
      - count
      - data
      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