AgentFilings Earnings API

openapi: 3.2.0
info:
  title: AgentFilings Earnings API
  version: 1.0.0
  description: 'Structured US SEC/EDGAR filing data for autonomous agents: filings index, XBRL-derived earnings summaries, and Form 4 insider transactions as clean JSON. Public-domain SEC data, pre-parsed and normalized. Paid endpoints use x402 (USDC on Base); /health and /probe are free. Call /probe first to check coverage and pricing before paying.'
  contact:
    email: ekrishtul@yahoo.com
  license:
    name: 'Data: US SEC EDGAR (public domain)'
  x-guidance: 'Call GET /probe?ticker=SYMBOL first — it is free and tells you whether the ticker is covered, how much data exists, how fresh it is, and the exact price of each endpoint. If ticker_coverage.covered is false, do not pay: paid endpoints will return 404. Paid endpoints answer HTTP 402 with payment requirements in the base64 PAYMENT-REQUIRED header (x402 v2, USDC on Base mainnet); pay and retry the identical request. Every response is { data, meta }, and meta carries the SEC source accession and timestamps so figures can be traced back to the original filing. Coverage is US public companies filing with SEC EDGAR and is still expanding — call /probe for the authoritative answer on any specific ticker rather than assuming an index.'
servers:
- url: https://api.agentfilings.com
tags:
- name: Earnings
paths:
  /earnings/summary:
    get:
      operationId: earnings_summary
      summary: Structured earnings summary from XBRL company facts (no PDF parsing)
      parameters:
      - name: ticker
        in: query
        required: true
        schema:
          type: string
        description: Ticker symbol, e.g. AAPL.
      - name: period
        in: query
        required: false
        schema:
          type: string
        description: 'Optional filter: "annual", "quarterly", "interim", a fiscal year ("2025"/"FY2025"), or an SEC frame ("CY2026Q1").'
      security: []
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.02'
        protocols:
        - x402:
            network: base
            asset: USDC
            scheme: exact
      responses:
        '200':
          description: 'Success. Envelope: { data, meta } where meta carries source and freshness.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment required. Payment requirements are returned in the base64 PAYMENT-REQUIRED header (x402 v2), not the body.
        '404':
          description: No coverage for the requested ticker. Check /probe first — it is free.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Earnings
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - hint
          properties:
            code:
              type: string
            message:
              type: string
            hint:
              type: string
    Envelope:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          description: Endpoint-specific payload.
        meta:
          type: object
          required:
          - retrieved_at
          - cache
          properties:
            source_api:
              type: string
            source_accession:
              type: string
            filed_at:
              type:
              - string
              - 'null'
            retrieved_at:
              type: string
              format: date-time
            cache:
              type: string
              enum:
              - hit
              - miss