공시.ai Companies API

openapi: 3.2.0
info:
  title: 0si.ai Disclosure Companies 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: Companies
paths:
  /companies:
    get:
      operationId: listCompanies
      summary: Search or batch-fetch Korean and US listed companies and current fundamentals
      parameters:
      - name: q
        in: query
        schema:
          type: string
          maxLength: 120
      - name: market
        in: query
        schema:
          type: string
          enum:
          - KOSPI
          - KOSDAQ
          - KONEX
          - US
      - name: sector
        in: query
        schema:
          type: string
          maxLength: 80
      - name: stock_code
        in: query
        style: form
        explode: true
        schema:
          type: array
          maxItems: 50
          items:
            type: string
      - name: cursor
        in: query
        schema:
          type: string
          maxLength: 15
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Company list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyList'
          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'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Companies
  /companies/{stock_code}:
    get:
      operationId: getCompany
      summary: Get point-in-time company fundamentals and share data
      parameters:
      - name: stock_code
        in: path
        required: true
        schema:
          type: string
          pattern: ^(?:[0-9]{6}|[A-Z][A-Z0-9.-]{0,14})$
        examples:
          kr:
            value: 005930
          us:
            value: AAPL
      responses:
        '200':
          description: Company asset intelligence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyDetail'
          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:
      - Companies
  /companies/{stock_code}/fundamentals/history:
    get:
      operationId: listCompanyFundamentalHistory
      summary: List point-in-time company asset snapshots
      parameters:
      - name: stock_code
        in: path
        required: true
        schema:
          type: string
          pattern: ^(?:[0-9]{6}|[A-Z][A-Z0-9.-]{0,14})$
      - name: cursor
        in: query
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Historical asset snapshots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundamentalHistoryList'
          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'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Companies
components:
  responses:
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request parameters are invalid
      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'
    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:
    Error:
      type: object
      properties:
        detail:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
      description: ''
    CompanyList:
      type: object
      required:
      - object
      - data
      - pagination
      - meta
      properties:
        object:
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/AssetSnapshot'
        pagination:
          type: object
          additionalProperties: true
        meta:
          type: object
          additionalProperties: true
    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'
    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
    Pagination:
      type: object
      required:
      - count
      - has_more
      properties:
        count:
          type: integer
        has_more:
          type: boolean
        next_cursor:
          type:
          - string
          - 'null'
    FundamentalHistoryList:
      type: object
      required:
      - object
      - data
      - meta
      - pagination
      properties:
        object:
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/FundamentalSnapshot'
        meta:
          $ref: '#/components/schemas/Meta'
        pagination:
          $ref: '#/components/schemas/Pagination'
    FundamentalSnapshot:
      allOf:
      - $ref: '#/components/schemas/AssetSnapshot'
      - type: object
        properties:
          snapshot_id:
            type: string
            format: uuid
            description: Cursor for the next page
    CompanyDetail:
      type: object
      required:
      - object
      - data
      - meta
      properties:
        object:
          const: company
        data:
          $ref: '#/components/schemas/AssetSnapshot'
        meta:
          type: object
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: osi_live_...
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key