공시.ai Sec API

openapi: 3.2.0
info:
  title: 0si.ai Disclosure Sec API
  version: 1.5.0
  description: 'Analyzed Korean disclosures and US SEC filings, structured deltas, point-in-time fundamentals, filtered signed webhooks and replayable realtime SSE events. Pro keys use every endpoint at 120 requests per minute. Any signed-in account can create one trial key: REST reads only, 10 requests per minute and 100 per day (UTC), with the free plan''s 30-second publication delay; streams and webhooks return pro_plan_required. Developer events can be replayed for 30 days. Prepaid credits (where enabled): after the free daily allowance each successful call spends one credit, failed calls are never charged, and /status and /usage are always free. Responses report X-Credits-Charged, X-Credits-Remaining and X-Free-Requests-Remaining; with no credits left the API returns 402 insufficient_credits with a top_up_url for the account owner. Each key or MCP connection can carry a monthly credit budget set by its owner (MCP connections start at 2,000 credits); reaching it returns 402 key_budget_exceeded with a settings_url.'
  contact:
    name: 0si.ai developer support
    email: ops@0si.ai
    url: https://0si.ai/support
  termsOfService: https://0si.ai/terms
servers:
- url: https://app.0si.ai/api/v1
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Sec
paths:
  /sec/filings:
    get:
      operationId: listSecFilings
      summary: List analyzed US SEC filings
      description: US-only convenience endpoint. It returns the same stable Disclosure contract as /disclosures?market=US&source=SEC.
      parameters:
      - name: cursor
        in: query
        schema:
          type: integer
          minimum: 0
        description: Return filings older than this sequence.
      - name: after
        in: query
        schema:
          type: integer
          minimum: 0
        description: Return filings newer than this sequence in ascending order.
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: ticker
        in: query
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9.-]{0,14}$
      - name: cik
        in: query
        schema:
          type: string
          pattern: ^[0-9]{1,10}$
      - name: form
        in: query
        style: form
        explode: true
        schema:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/SecForm'
        description: Repeat for multiple base forms. Amendments are included with their base form.
      - name: periodic_only
        in: query
        schema:
          type: boolean
          default: false
      - name: q
        in: query
        schema:
          type: string
          maxLength: 120
      - name: sentiment
        in: query
        style: form
        explode: true
        schema:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/Sentiment'
      - name: submitted_from
        in: query
        schema:
          type: string
          format: date-time
      - name: submitted_to
        in: query
        schema:
          type: string
          format: date-time
      - name: watchlist
        in: query
        schema:
          type: boolean
          default: false
        description: Only stocks saved in the key owner's 0si.ai watchlist.
      responses:
        '200':
          description: SEC filing list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisclosureList'
          headers:
            X-Credits-Charged:
              description: Credits spent by this call (0 or 1). Sent when credits are enabled for the account; failed calls are never charged.
              schema:
                type: integer
            X-Credits-Remaining:
              description: Credit balance after this call. Sent when credits are enabled for the account.
              schema:
                type: integer
            X-Free-Requests-Remaining:
              description: Free calls left today (UTC) for trial and credit plans.
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Sec
  /sec/filings/{accession_number}:
    get:
      operationId: getSecFiling
      summary: Get a US SEC filing by accession number
      parameters:
      - $ref: '#/components/parameters/SecAccessionNumber'
      responses:
        '200':
          description: SEC filing detail and collected source text
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisclosureDetail'
          headers:
            X-Credits-Charged:
              description: Credits spent by this call (0 or 1). Sent when credits are enabled for the account; failed calls are never charged.
              schema:
                type: integer
            X-Credits-Remaining:
              description: Credit balance after this call. Sent when credits are enabled for the account.
              schema:
                type: integer
            X-Free-Requests-Remaining:
              description: Free calls left today (UTC) for trial and credit plans.
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Sec
  /sec/filings/{accession_number}/delta:
    get:
      operationId: getSecFilingDelta
      summary: Get structured Delta for a US SEC periodic filing
      description: 10-Q, 10-K, 20-F, and 40-F filings expose SEC XBRL-based periodic_delta when comparable facts are available.
      parameters:
      - $ref: '#/components/parameters/SecAccessionNumber'
      responses:
        '200':
          description: Structured SEC filing Delta or available=false
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeltaResponse'
          headers:
            X-Credits-Charged:
              description: Credits spent by this call (0 or 1). Sent when credits are enabled for the account; failed calls are never charged.
              schema:
                type: integer
            X-Credits-Remaining:
              description: Credit balance after this call. Sent when credits are enabled for the account.
              schema:
                type: integer
            X-Free-Requests-Remaining:
              description: Free calls left today (UTC) for trial and credit plans.
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Sec
  /sec/stream:
    get:
      operationId: streamSecFilings
      summary: Stream US SEC filing events with Server-Sent Events
      parameters:
      - name: cursor
        in: query
        schema:
          type: integer
          minimum: 0
      - name: form
        in: query
        style: form
        explode: true
        schema:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/SecForm'
      - name: ticker
        in: query
        style: form
        explode: true
        schema:
          type: array
          maxItems: 100
          items:
            type: string
            maxLength: 15
        description: Repeat for up to 100 US tickers.
      - name: sentiment
        in: query
        style: form
        explode: true
        schema:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/Sentiment'
        description: Repeat to match any of the listed sentiments. Non-material corrections count as neutral.
      - name: watchlist
        in: query
        schema:
          type: boolean
          default: false
        description: Only stocks saved in the key owner's 0si.ai watchlist.
      - name: Last-Event-ID
        in: header
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: Replayable US-only SEC filing stream
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Sec
components:
  responses:
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: API key is missing, invalid, or revoked
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit, trial daily quota (daily_quota_exceeded) or concurrent stream limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Insufficient scope, or pro_plan_required for streams and webhooks on a trial key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientCredits:
      description: 'insufficient_credits: the free daily allowance (or Pro''s included monthly calls) is used up and the account has no credits; ask the owner to top up at top_up_url. key_budget_exceeded: this key or MCP connection reached the monthly credit budget its owner set (other keys are unaffected); ask the owner to raise it at settings_url. Do not retry either until the owner acts.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InsufficientCreditsError'
  schemas:
    DeveloperEvent:
      type: object
      required:
      - id
      - type
      - reason
      - occurred_at
      - analysis_status_at_event
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
          - disclosure.created
          - disclosure.updated
        reason:
          type: string
        occurred_at:
          type: string
          format: date-time
        analysis_status_at_event:
          type: string
          description: Immutable analysis status captured when this event was created. It always matches analysis.status in the same event payload.
    PeriodicDelta:
      type: object
      required:
      - schema_version
      - type
      - metrics
      properties:
        schema_version:
          const: 1
        type:
          const: periodic_delta
        label:
          type: string
          example: SEC 실적 Delta
        headline:
          type: string
        description:
          type: string
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/PeriodicMetric'
        metadata:
          type: array
          items:
            type: object
            additionalProperties: true
        source_note:
          type: string
      additionalProperties: true
    EarningsCumulative:
      type: object
      required:
      - current
      - yoy
      properties:
        current:
          $ref: '#/components/schemas/Amount'
        yoy:
          oneOf:
          - $ref: '#/components/schemas/EarningsComparison'
          - type: 'null'
    EarningsComparison:
      type: object
      required:
      - rate_pct
      - transition
      - label
      - direction
      - prior
      - period
      properties:
        rate_pct:
          type:
          - number
          - 'null'
          description: Percentage change. Null for transitions such as profit turnaround.
        transition:
          type:
          - string
          - 'null'
          description: 흑자전환 or 적자전환 when a percentage is not meaningful.
        label:
          type: string
        direction:
          type: string
          enum:
          - up
          - down
          - flat
        prior:
          $ref: '#/components/schemas/Amount'
        period:
          type: string
    SecMetadata:
      type: object
      required:
      - accession_number
      - cik
      - form
      - base_form
      - is_amendment
      - is_periodic
      - report_period
      - fiscal_year
      properties:
        accession_number:
          type: string
          pattern: ^[0-9]{10}-[0-9]{2}-[0-9]{6}$
        cik:
          type: string
          pattern: ^$|^[0-9]{10}$
        form:
          $ref: '#/components/schemas/SecForm'
        base_form:
          $ref: '#/components/schemas/SecForm'
        is_amendment:
          type: boolean
        is_periodic:
          type: boolean
        report_period:
          type: string
          description: XBRL reporting period when available.
        fiscal_year:
          type: string
    InsufficientCreditsError:
      type: object
      properties:
        detail:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - insufficient_credits
              - key_budget_exceeded
            message:
              type: string
            top_up_url:
              type: string
              format: uri
              description: 'insufficient_credits: page where the account owner can buy credits'
            settings_url:
              type: string
              format: uri
              description: 'key_budget_exceeded: page where the owner can raise this key''s monthly budget'
            monthly_limit:
              type: integer
              description: 'key_budget_exceeded: the key''s monthly credit budget'
    CorrectionDelta:
      type: object
      required:
      - schema_version
      - type
      - changes
      properties:
        schema_version:
          const: 1
        type:
          const: correction_delta
        materiality:
          type: string
        changes:
          type: array
          items:
            type: object
            additionalProperties: true
        corporate_action:
          $ref: '#/components/schemas/CorporateActionDelta'
      additionalProperties: true
    DisclosureScale:
      type: object
      properties:
        metrics:
          type: array
          items:
            type: object
            additionalProperties: true
        primary_metric:
          type:
          - object
          - 'null'
          additionalProperties: true
      additionalProperties: true
    Amount:
      type: object
      required:
      - value
      - display
      properties:
        value:
          type:
          - number
          - 'null'
        display:
          type: string
    CorporateActionDelta:
      type: object
      required:
      - schema_version
      - type
      - action_type
      - status
      - confidence
      properties:
        schema_version:
          const: 1
        type:
          const: corporate_action_delta
        action_type:
          type: string
          enum:
          - contract
          - dividend
          - buyback
          - retirement
          - capital_raise
          - convertible
          - share_split
          - capital_reduction
          - other
        status:
          type: string
        amount_krw:
          type:
          - number
          - 'null'
        share_count:
          type:
          - number
          - 'null'
        issued_share_delta:
          type:
          - number
          - 'null'
        maximum_dilution_shares:
          type:
          - number
          - 'null'
        price_per_share:
          type:
          - number
          - 'null'
        ratio_pct:
          type:
          - number
          - 'null'
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
        details:
          type: object
          additionalProperties: true
    Sentiment:
      type: string
      enum:
      - very_positive
      - positive
      - neutral
      - negative
      - very_negative
    GenericDelta:
      oneOf:
      - $ref: '#/components/schemas/EarningsDelta'
      - $ref: '#/components/schemas/PeriodicDelta'
      - $ref: '#/components/schemas/CorrectionDelta'
      - $ref: '#/components/schemas/CorporateActionDelta'
    Disclosure:
      type: object
      required:
      - id
      - sequence
      - company_name
      - jurisdiction
      - title
      - source
      - analysis
      - market_reaction
      properties:
        id:
          type: string
        sequence:
          type: integer
        stock_code:
          type: string
        company_name:
          type: string
        market:
          type: string
        jurisdiction:
          type: string
          enum:
          - KR
          - US
        sector:
          type: string
        title:
          type: string
        source:
          type: string
        source_label:
          type: string
        filing_form:
          type: string
          description: SEC form such as 8-K or 10-Q; empty for Korean disclosures.
        sec:
          oneOf:
          - $ref: '#/components/schemas/SecMetadata'
          - type: 'null'
          description: Present for SEC filings and omitted for Korean disclosures.
        source_url:
          type: string
          format: uri
        submitted_at:
          type:
          - string
          - 'null'
          format: date-time
        detected_at:
          type:
          - string
          - 'null'
          format: date-time
        published_at:
          type:
          - string
          - 'null'
          format: date-time
        analysis:
          $ref: '#/components/schemas/Analysis'
        earnings_delta:
          $ref: '#/components/schemas/EarningsDelta'
        delta:
          $ref: '#/components/schemas/GenericDelta'
        market_reaction:
          type: object
          additionalProperties: true
        event:
          $ref: '#/components/schemas/DeveloperEvent'
    AssetSnapshot:
      type: object
      properties:
        stock_code:
          type: string
        company_name:
          type: string
        market:
          type: string
        sector:
          type: string
        listing_status:
          type: string
        instrument_key:
          type: string
          example: US:AAPL
        country_code:
          type: string
          enum:
          - KR
          - US
        currency:
          type: string
          example: USD
        exchange:
          type: string
          example: NASDAQ
        cik:
          type: string
        metrics:
          type: object
          additionalProperties: true
        shares:
          type: object
          additionalProperties: true
        financials:
          type: object
          additionalProperties: true
        quote:
          type: object
          additionalProperties: true
        basis:
          type: object
          additionalProperties: true
        pending_actions:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    Meta:
      type: object
      required:
      - request_id
      - generated_at
      - api_version
      properties:
        request_id:
          type: string
        generated_at:
          type: string
          format: date-time
        api_version:
          type: string
          const: v1
    DisclosureList:
      type: object
      required:
      - object
      - data
      - pagination
      - meta
      properties:
        object:
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Disclosure'
        pagination:
          type: object
          additionalProperties: true
        meta:
          type: object
          additionalProperties: true
    EarningsMetric:
      type: object
      required:
      - key
      - label
      - current
      - qoq
      - yoy
      - cumulative
      properties:
        key:
          type: string
          pattern: ^(revenue|operating_income|net_income|parent_net_income|diluted_eps|country:[^:]+:(revenue|operating_income|net_income|parent_net_income))$
        label:
          type: string
        scope:
          type: string
          description: Country/entity scope for monthly earnings, not consolidated totals.
        current:
          $ref: '#/components/schemas/Amount'
        qoq:
          oneOf:
          - $ref: '#/components/schemas/EarningsComparison'
          - type: 'null'
        mom:
          description: Month-over-month comparison. Present for period_type=month; qoq is null in that case.
          oneOf:
          - $ref: '#/components/schemas/EarningsComparison'
          - type: 'null'
        yoy:
          oneOf:
          - $ref: '#/components/schemas/EarningsComparison'
          - type: 'null'
        cumulative:
          oneOf:
          - $ref: '#/components/schemas/EarningsCumulative'
          - type: 'null'
    Analysis:
      type: object
      required:
      - status
      - signal
      - signal_label
      - confidence
      - summary
      - key_points
      - risk_flags
      - tags
      properties:
        status:
          type: string
          example: succeeded
          description: Current status in REST responses. In SSE and webhook event payloads, this is the immutable status at event time and matches event.analysis_status_at_event.
        signal:
          $ref: '#/components/schemas/Sentiment'
        signal_label:
          type: string
          example: 긍정
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
        summary:
          type: string
        key_points:
          type: array
          items:
            type: string
        risk_flags:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        is_correction:
          type: boolean
        correction_materiality:
          type: string
    PeriodicMetric:
      type: object
      required:
      - key
      - label
      - current
      - prior
      - change
      - change_value
      - direction
      - period
      - prior_period
      - comparison_basis
      properties:
        key:
          type: string
          enum:
          - revenue
          - operating_income
          - net_income
          - diluted_eps
          - assets
          - liabilities
          - equity
          - cash
          - operating_cash_flow
        label:
          type: string
        current:
          type: string
          example: $12.4B
        prior:
          type: string
          example: $10.8B
        change:
          type: string
          example: +14.8%
        change_value:
          type:
          - number
          - 'null'
          example: 14.8
        direction:
          type: string
          enum:
          - up
          - down
          - flat
        period:
          type: string
          example: '2026-06-30'
        prior_period:
          type: string
          example: '2025-06-30'
        comparison_basis:
          type: string
          example: 전년 동기
        comparisons:
          type: array
          items:
            type: object
            additionalProperties: true
        ttm:
          type: string
          example: $44.2B
    Error:
      type: object
      properties:
        detail:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
      description: ''
    DeltaResponse:
      type: object
      required:
      - object
      - data
      - meta
      properties:
        object:
          const: disclosure_delta
        data:
          type: object
          required:
          - disclosure_id
          - available
          - delta
          properties:
            disclosure_id:
              type: string
            accession_number:
              type: string
              description: SEC filings only
            available:
              type: boolean
              description: false when no structured delta exists for this filing
            delta:
              oneOf:
              - $ref: '#/components/schemas/GenericDelta'
              - type: 'null'
        meta:
          $ref: '#/components/schemas/Meta'
    DisclosureDetail:
      type: object
      required:
      - object
      - data
      - meta
      properties:
        object:
          const: disclosure
        data:
          allOf:
          - $ref: '#/components/schemas/Disclosure'
          - type: object
            properties:
              document:
                type: object
                properties:
                  text:
                    type: string
                  character_count:
                    type: integer
              asset_snapshot:
                $ref: '#/components/schemas/AssetSnapshot'
              disclosure_scale:
                $ref: '#/components/schemas/DisclosureScale'
        meta:
          type: object
          additionalProperties: true
    SecForm:
      type: string
      pattern: ^[A-Z0-9][A-Z0-9 .-]{0,30}(/A)?$
      examples:
      - 8-K
      - 10-Q
      - 10-K
      - 20-F
      - 40-F
      - 6-K
    EarningsDelta:
      type: object
      required:
      - schema_version
      - type
      - period
      - basis
      - basis_label
      - unit
      - is_correction
      - metrics
      - source_note
      properties:
        schema_version:
          const: 1
        type:
          const: earnings_delta
        period_type:
          type: string
          enum:
          - month
          description: Optional discriminator for monthly country/entity earnings.
        period:
          type: string
          example: 2026년 2분기
        basis:
          type: string
          enum:
          - consolidated
          - separate
          - unknown
        basis_label:
          type: string
          example: 연결
        unit:
          type: string
          example: 백만원
        is_correction:
          type: boolean
        metrics:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EarningsMetric'
        source_note:
          type: string
  parameters:
    SecAccessionNumber:
      name: accession_number
      in: path
      required: true
      schema:
        type: string
        pattern: ^[0-9]{10}-[0-9]{2}-[0-9]{6}$
      example: 0000320193-26-000079
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: osi_live_...
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key