Equity Rank Ingest API

openapi: 3.2.0
info:
  title: Equity Rank Com Ingest API
  version: 0.1.0
  description: 'Operations tagged ingest across 2 of this provider''s published API definitions: openapi.json, equity-rank-com-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Ingest
paths:
  /api/ingest/edgar-pit:
    post:
      tags:
      - Ingest
      summary: Ingest Edgar Pit
      operationId: ingest_edgar_pit_api_ingest_edgar_pit_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestBatch'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/ingest/edgar-pit/delisted-universe:
    get:
      tags:
      - Ingest
      summary: Edgar Delisted Universe
      description: 'Everything the loader''s DELISTED universe needs from the DB, so the runner holds

        no DB credential (2026-10-08, migration 237, `research_edgar_delisted_universe_json`):

        tails -- per research.px_monthly delisted symbol: n_months, ever_tradeable,

        last_obs (what `delisted_fundamentals_pilot.panel_tails` read with

        the management token);

        mapped -- edgar_cik_map rows with a delisted_on (the `_already_mapped` resume);

        loaded_ciks -- distinct edgar_fundamentals_pit CIKs (the `_already_loaded_ciks`

        resume), so a re-run re-fetches nothing from SEC that is stored.

        One scalar-jsonb RPC (mig 210''s contract: no 1,000-row db-max-rows cap, no paging).

        Read-only; the AV delisted register is fetched on the runner with its own secret.'
      operationId: edgar_delisted_universe_api_ingest_edgar_pit_delisted_universe_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelistedUniverse'
      security:
      - HTTPBearer: []
  /api/ingest/research-rows:
    post:
      tags:
      - Ingest
      summary: Ingest Research Rows
      description: 'Validate row-by-row, not batch-wide. Before 2026-10-01 a single malformed row

        (e.g. a non-ISO date that slipped past the shaping script) 422''d the ENTIRE

        request, and `edgar_pit_ingest_client.post_all` treats any 4xx as fatal and aborts

        the whole run -- the Owner Daily Desk `insider-history` pull landed only 6 of

        ~6,811 symbols because one bad row, thousands of rows in, killed every batch after

        it (the rows already fetched were never lost -- they just never got re-sent,

        because the run died). A 422 is now reserved for a structurally wrong request (an

        unknown table, or a batch where EVERY row fails); a batch with some good and some

        bad rows inserts the good ones and reports the rest as `rows_rejected` so the

        caller can see it without the run dying.'
      operationId: ingest_research_rows_api_ingest_research_rows_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResearchRowsBatch'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchRowsResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/ingest/research-universe/dividends:
    get:
      tags:
      - Ingest
      summary: Research Dividend Universe
      description: 'The delisted-dividend backfill''s symbol list, computed in the DB

        (`public.research_dividend_universe_json()`, migration 210, over migration 209''s

        set-returning function): every symbol in the research price panel with no

        dividend_history row. Served to the runner so it never needs a committed list or

        DB access.'
      operationId: research_dividend_universe_api_ingest_research_universe_dividends_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DividendUniverse'
      security:
      - HTTPBearer: []
  /api/ingest/research-universe/{kind}:
    get:
      tags:
      - Ingest
      summary: Research Desk Universe
      description: 'Owner Daily Desk pull universes (migrations 217/230,

        `research_desk_universe_json`): `earnings` = research-panel common stocks with no

        earnings_surprise_history row yet; `splits` = delisted panel names with no

        split_history row. Same one-scalar-jsonb contract as the dividends universe above.

        (The `insider` kind was dropped with `insider_transactions_history` in mig 230.)'
      operationId: research_desk_universe_api_ingest_research_universe__kind__get
      security:
      - HTTPBearer: []
      parameters:
      - name: kind
        in: path
        required: true
        schema:
          type: string
          title: Kind
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DividendUniverse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/ingest/research-export/{table}:
    get:
      tags:
      - Ingest
      summary: Research Export
      description: 'One keyset page of an allowlisted research-panel input. `next_after` is the last

        row''s keyset (send it back as `after`), or null on a short page (the end).

        `with_total=true` adds the table''s exact row count so the runner can prove it read

        every row.'
      operationId: research_export_api_ingest_research_export__table__get
      security:
      - HTTPBearer: []
      parameters:
      - name: table
        in: path
        required: true
        schema:
          type: string
          title: Table
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: After
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 5000
          title: Limit
      - name: with_total
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: With Total
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportPage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/ingest/normalized-track-snapshot:
    get:
      tags:
      - Ingest
      summary: Normalized Track Snapshot
      description: 'NORM-MULT-01 Stage B: the month''s read-only snapshot (port of the builder''s

        `snapshot.sql`) for `.github/workflows/normalized-paper-track.yml`, which commits it.

        Reads screener_cache + statement_history; writes nothing.'
      operationId: normalized_track_snapshot_api_ingest_normalized_track_snapshot_get
      security:
      - HTTPBearer: []
      parameters:
      - name: as_of
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: As Of
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Normalized Track Snapshot Api Ingest Normalized Track Snapshot Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/ingest/actions-usage:
    post:
      tags:
      - Ingest
      summary: Ingest Actions Usage
      description: 'Record the day''s GitHub Actions usage check as a `cron_runs` row (job

        `actions-budget`). Under budget it is a plain `success`; on course to pass 60% of

        the budget it is stored as status `over_budget` with the plain-English summary in

        `error_message`, which the daily anomaly review''s failed-job check already

        surfaces. No new table: one row a day in the table that review reads.'
      operationId: ingest_actions_usage_api_ingest_actions_usage_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionsUsageReport'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Ingest Actions Usage Api Ingest Actions Usage Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/ingest/open-prs:
    post:
      tags:
      - Ingest
      summary: Ingest Open Prs
      description: 'Store the day''s open pull request list in `app_config` (key `open_pr_watch`)

        as JSON text with the time it was checked. One row, replaced each day.'
      operationId: ingest_open_prs_api_ingest_open_prs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenPrReport'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Ingest Open Prs Api Ingest Open Prs Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    CikMapRow:
      properties:
        ticker:
          type: string
          maxLength: 12
          minLength: 1
          title: Ticker
        cik:
          type: string
          title: Cik
        entity_name:
          type: string
          maxLength: 300
          minLength: 1
          title: Entity Name
        delisted_on:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Delisted On
        match_method:
          type: string
          maxLength: 64
          minLength: 1
          title: Match Method
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
          title: Confidence
      type: object
      required:
      - ticker
      - cik
      - entity_name
      - match_method
      - confidence
      title: CikMapRow
    OpenPrReport:
      properties:
        prs:
          items:
            $ref: '#/components/schemas/OpenPr'
          type: array
          maxItems: 200
          title: Prs
      type: object
      title: OpenPrReport
    ActionsUsageReport:
      properties:
        month:
          type: string
          pattern: ^\d{4}-\d{2}$
          title: Month
        level:
          type: string
          enum:
          - ok
          - warning
          - critical
          title: Level
        minutes_to_date:
          type: integer
          minimum: 0.0
          title: Minutes To Date
        projected_minutes:
          type: integer
          minimum: 0.0
          title: Projected Minutes
        projected_usd:
          type: number
          minimum: 0.0
          title: Projected Usd
        message:
          type: string
          maxLength: 600
          minLength: 1
          title: Message
      type: object
      required:
      - month
      - level
      - minutes_to_date
      - projected_minutes
      - projected_usd
      - message
      title: ActionsUsageReport
      description: The summary `scripts/actions-usage.mjs` writes, reduced to what is stored.
    FactRow:
      properties:
        cik:
          type: string
          title: Cik
        ticker:
          type: string
          maxLength: 12
          minLength: 1
          title: Ticker
        entity_name:
          type: string
          maxLength: 300
          minLength: 1
          title: Entity Name
        concept:
          type: string
          title: Concept
        xbrl_tag:
          type: string
          maxLength: 200
          minLength: 3
          title: Xbrl Tag
        unit:
          type: string
          maxLength: 64
          minLength: 1
          title: Unit
        period_start:
          type: string
          format: date
          title: Period Start
        period_end:
          type: string
          format: date
          title: Period End
        fiscal_year:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fiscal Year
        fiscal_period:
          anyOf:
          - type: string
            maxLength: 8
          - type: 'null'
          title: Fiscal Period
        form:
          type: string
          maxLength: 16
          minLength: 1
          title: Form
        filed:
          type: string
          format: date
          title: Filed
        value:
          type: number
          title: Value
        accession:
          type: string
          maxLength: 40
          minLength: 1
          title: Accession
        frame:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: Frame
        source:
          type: string
          const: edgar
          title: Source
          default: edgar
      type: object
      required:
      - cik
      - ticker
      - entity_name
      - concept
      - xbrl_tag
      - unit
      - period_start
      - period_end
      - form
      - filed
      - value
      - accession
      title: FactRow
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResearchRowsResult:
      properties:
        table:
          type: string
          title: Table
        rows_sent:
          type: integer
          title: Rows Sent
        rows_rejected:
          type: integer
          title: Rows Rejected
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
      type: object
      required:
      - table
      - rows_sent
      - rows_rejected
      - run_id
      title: ResearchRowsResult
    ExportPage:
      properties:
        table:
          type: string
          title: Table
        rows:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Rows
        next_after:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Next After
        total:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total
      type: object
      required:
      - table
      - rows
      - next_after
      title: ExportPage
    OpenPr:
      properties:
        number:
          type: integer
          minimum: 1.0
          title: Number
        title:
          type: string
          maxLength: 300
          title: Title
        branch:
          type: string
          maxLength: 200
          title: Branch
          default: ''
        draft:
          type: boolean
          title: Draft
          default: false
        created_at:
          type: string
          maxLength: 40
          minLength: 10
          title: Created At
        labels:
          items:
            type: string
          type: array
          maxItems: 30
          title: Labels
      type: object
      required:
      - number
      - title
      - created_at
      title: OpenPr
    DividendUniverse:
      properties:
        symbols:
          items:
            type: string
          type: array
          title: Symbols
        delisted:
          items:
            type: string
          type: array
          title: Delisted
      type: object
      required:
      - symbols
      - delisted
      title: DividendUniverse
    IngestBatch:
      properties:
        cik_map:
          items:
            $ref: '#/components/schemas/CikMapRow'
          type: array
          maxItems: 1000
          title: Cik Map
        facts:
          items:
            $ref: '#/components/schemas/FactRow'
          type: array
          maxItems: 1000
          title: Facts
      type: object
      title: IngestBatch
    ResearchRowsBatch:
      properties:
        table:
          type: string
          enum:
          - listing_status_snapshot
          - dividend_history
          - split_history
          - earnings_surprise_history
          - benchmark_price_history
          title: Table
        rows:
          items:
            additionalProperties: true
            type: object
          type: array
          maxItems: 1000
          title: Rows
      type: object
      required:
      - table
      title: ResearchRowsBatch
    DelistedUniverse:
      properties:
        tails:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Tails
        mapped:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Mapped
        loaded_ciks:
          items:
            type: string
          type: array
          title: Loaded Ciks
      type: object
      required:
      - tails
      - mapped
      - loaded_ciks
      title: DelistedUniverse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    IngestResult:
      properties:
        cik_map_sent:
          type: integer
          title: Cik Map Sent
        facts_sent:
          type: integer
          title: Facts Sent
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
        ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Ref
      type: object
      required:
      - cik_map_sent
      - facts_sent
      - run_id
      - ref
      title: IngestResult
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- openapi.json
- equity-rank-com-openapi.yml