공시.ai Webhooks API

openapi: 3.2.0
info:
  title: 0si.ai Disclosure Webhooks 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: Webhooks
paths:
  /webhooks:
    get:
      operationId: listWebhooks
      summary: List signed webhook endpoints
      responses:
        '200':
          description: Webhook list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
          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
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Webhooks
    post:
      operationId: createWebhook
      summary: Create a signed HTTPS webhook endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: Webhook and one-time signing secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreated'
          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:
      - Webhooks
  /webhooks/{webhook_id}:
    patch:
      operationId: updateWebhook
      summary: Update or pause a webhook
      parameters:
      - $ref: '#/components/parameters/WebhookId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '200':
          description: Updated webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
          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
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Webhooks
    delete:
      operationId: deleteWebhook
      summary: Delete a webhook and its delivery history
      parameters:
      - $ref: '#/components/parameters/WebhookId'
      responses:
        '200':
          description: Webhook deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeleted'
          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
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Webhooks
  /webhooks/{webhook_id}/test:
    post:
      operationId: testWebhook
      summary: Queue a signed webhook.test delivery
      parameters:
      - $ref: '#/components/parameters/WebhookId'
      responses:
        '202':
          description: Test delivery queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookTestQueued'
          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
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Webhooks
  /webhooks/{webhook_id}/rotate-secret:
    post:
      operationId: rotateWebhookSecret
      summary: Rotate and return a new signing secret once
      parameters:
      - $ref: '#/components/parameters/WebhookId'
      responses:
        '200':
          description: New one-time signing secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSecretResponse'
          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
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Webhooks
  /webhooks/{webhook_id}/deliveries:
    get:
      operationId: listWebhookDeliveries
      summary: Inspect webhook attempts and response status
      parameters:
      - $ref: '#/components/parameters/WebhookId'
      - 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: Delivery history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryList'
          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
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      tags:
      - Webhooks
components:
  schemas:
    WebhookInput:
      type: object
      required:
      - name
      - url
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 60
        url:
          type: string
          format: uri
          description: Public HTTPS endpoint on port 443.
        events:
          type: array
          minItems: 1
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
            - disclosure.created
            - disclosure.updated
        markets:
          type: array
          minItems: 1
          maxItems: 2
          uniqueItems: true
          default:
          - KR
          - US
          items:
            type: string
            enum:
            - KR
            - US
          description: Delivery markets. Existing and omitted configurations receive both markets.
        filing_forms:
          type: array
          maxItems: 20
          uniqueItems: true
          default: []
          items:
            $ref: '#/components/schemas/SecForm'
          description: Optional SEC base-form filter. Applies only to US events and includes amendments.
        stock_codes:
          type: array
          maxItems: 100
          uniqueItems: true
          default: []
          items:
            type: string
            maxLength: 15
          description: Optional Korean stock codes or US tickers. Empty delivers every stock.
        sentiments:
          type: array
          maxItems: 5
          uniqueItems: true
          default: []
          items:
            $ref: '#/components/schemas/Sentiment'
          description: Optional sentiment filter evaluated when the event is recorded.
        watchlist_only:
          type: boolean
          default: false
          description: Deliver only stocks saved in the owner's 0si.ai watchlist at event time.
        enabled:
          type: boolean
          default: true
    WebhookDeliveryList:
      type: object
      required:
      - object
      - data
      - meta
      - pagination
      properties:
        object:
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookDelivery'
        meta:
          $ref: '#/components/schemas/Meta'
        pagination:
          $ref: '#/components/schemas/Pagination'
    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'
    WebhookList:
      type: object
      required:
      - object
      - data
      - meta
      - pagination
      properties:
        object:
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
        meta:
          $ref: '#/components/schemas/Meta'
        pagination:
          $ref: '#/components/schemas/Pagination'
    WebhookDelivery:
      type: object
      properties:
        id:
          type: string
        event_id:
          type:
          - integer
          - 'null'
        event_type:
          type: string
        status:
          type: string
          enum:
          - pending
          - delivered
          - failed
        attempts:
          type: integer
        next_attempt_at:
          type:
          - string
          - 'null'
          format: date-time
        response_status:
          type:
          - integer
          - 'null'
        latency_ms:
          type:
          - integer
          - 'null'
        error:
          type: string
        delivered_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
    Sentiment:
      type: string
      enum:
      - very_positive
      - positive
      - neutral
      - negative
      - very_negative
    WebhookResponse:
      type: object
      required:
      - object
      - data
      - meta
      properties:
        object:
          const: webhook
        data:
          $ref: '#/components/schemas/Webhook'
        meta:
          $ref: '#/components/schemas/Meta'
    WebhookSecretResponse:
      type: object
      required:
      - object
      - data
      - meta
      properties:
        object:
          const: webhook_secret
        data:
          type: object
          properties:
            webhook_id:
              type: string
              format: uuid
            secret_version:
              type: integer
            secret:
              type: string
              description: Shown only once
        meta:
          $ref: '#/components/schemas/Meta'
    WebhookTestQueued:
      type: object
      required:
      - object
      - data
      - meta
      properties:
        object:
          const: webhook_delivery
        data:
          type: object
          properties:
            id:
              type: string
            status:
              type: string
              const: pending
        meta:
          $ref: '#/components/schemas/Meta'
    WebhookCreated:
      type: object
      required:
      - object
      - data
      - meta
      - secret
      properties:
        object:
          const: webhook
        data:
          $ref: '#/components/schemas/Webhook'
        meta:
          $ref: '#/components/schemas/Meta'
        secret:
          type: string
          description: HMAC signing secret. Shown only once; store it in a secret manager.
        message:
          type: string
    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'
    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
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        markets:
          type: array
          items:
            type: string
            enum:
            - KR
            - US
        filing_forms:
          type: array
          items:
            type: string
        stock_codes:
          type: array
          items:
            type: string
        sentiments:
          type: array
          items:
            type: string
        watchlist_only:
          type: boolean
        enabled:
          type: boolean
        secret_version:
          type: integer
        last_success_at:
          type:
          - string
          - 'null'
          format: date-time
        last_failure_at:
          type:
          - string
          - 'null'
          format: date-time
        consecutive_failures:
          type: integer
        last_error:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        delivery_counts:
          type: object
          properties:
            pending:
              type: integer
            delivered:
              type: integer
            failed:
              type: integer
    WebhookDeleted:
      type: object
      required:
      - object
      - data
      - meta
      properties:
        object:
          const: webhook
        data:
          type: object
          properties:
            deleted:
              type: boolean
              const: true
        meta:
          $ref: '#/components/schemas/Meta'
    Error:
      type: object
      properties:
        detail:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
      description: ''
  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'
  parameters:
    WebhookId:
      name: webhook_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: osi_live_...
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key