openapi: 3.0.3
info:
  title: Zhane EDGAR API
  description: |
    Real-time SEC 8-K filing intelligence. Parsed, structured, and urgency-scored.

    The Zhane EDGAR API provides programmatic access to SEC EDGAR 8-K filings with:
    - Automatic item extraction (all 13 8-K item types)
    - Urgency scoring (LOW / MEDIUM / HIGH / CRITICAL)
    - Dollar amount parsing
    - 500-character context snippets per item
    - Real-time updates (10–30 seconds from SEC publication)

    All SEC EDGAR data is public domain. Zhane adds parsing, structure, and signal intelligence.
  version: 1.0.0
  contact:
    email: research@zctechnologies.org
    url: https://api.zctechnologies.org
  license:
    name: Proprietary
    url: https://api.zctechnologies.org/pricing
  x-logo:
    url: https://api.zctechnologies.org/logo.png

servers:
  - url: https://api.zctechnologies.org
    description: Production

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API key obtained after subscribing at https://api.zctechnologies.org/pricing.
        Keys begin with `zk_`.

  schemas:
    Item:
      type: object
      properties:
        name:
          type: string
          description: Human-readable name of the 8-K item
          example: Departure of Directors/Officers
        urgency:
          type: integer
          description: "Urgency score: 1=LOW, 2=MEDIUM, 3=HIGH, 4=CRITICAL"
          minimum: 1
          maximum: 4
          example: 3
        urgency_label:
          type: string
          enum: [LOW, MEDIUM, HIGH, CRITICAL]
          example: HIGH

    ItemWithContext:
      allOf:
        - $ref: '#/components/schemas/Item'
        - type: object
          properties:
            context:
              type: string
              description: Up to 500 characters of text following this item header in the filing
              example: "On March 15, 2026, the Company announced the resignation of John Smith..."

    Filing:
      type: object
      properties:
        accession:
          type: string
          description: SEC accession number
          pattern: '^\d{10}-\d{2}-\d{6}$'
          example: "0001193125-26-142364"
        company:
          type: string
          description: Company name from SEC EDGAR
          example: Goldman Sachs Private Credit Corp.
        cik:
          type: string
          description: Central Index Key
          example: "1920145"
        filed:
          type: string
          format: date
          description: Filing date
          example: "2026-04-03"
        updated:
          type: string
          format: date-time
          description: Last updated timestamp from SEC EDGAR
        items:
          type: object
          description: Map of item numbers found in the filing
          additionalProperties:
            $ref: '#/components/schemas/Item'
        max_urgency:
          type: integer
          description: Highest urgency score across all items
          minimum: 0
          maximum: 4
        max_urgency_label:
          type: string
          enum: [NONE, LOW, MEDIUM, HIGH, CRITICAL]
        index_url:
          type: string
          format: uri
          description: Direct link to SEC EDGAR filing index

    FilingDetail:
      type: object
      properties:
        accession:
          type: string
          example: "0001193125-26-142364"
        document_url:
          type: string
          format: uri
          description: Direct URL to the 8-K document on SEC.gov
        items:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ItemWithContext'
        dollar_amounts:
          type: array
          items:
            type: string
          description: All dollar figures extracted from the filing document
          example: ["$2.1 billion", "$450 million"]
        max_urgency:
          type: integer
          minimum: 0
          maximum: 4
        max_urgency_label:
          type: string
          enum: [NONE, LOW, MEDIUM, HIGH, CRITICAL]
        text_length:
          type: integer
          description: Total character count of the processed document text

    Error:
      type: object
      properties:
        error:
          type: string
        status:
          type: integer
      required: [error, status]

paths:
  /v1/filings/recent:
    get:
      summary: Recent 8-K Filings
      description: |
        Returns the most recent 8-K filings from SEC EDGAR, parsed and urgency-scored.

        **Free preview**: Without an Authorization header, returns 5 filings with limited fields.
        **Authenticated**: Returns up to 40 filings with full data.
      operationId: getRecentFilings
      security:
        - {}
        - BearerAuth: []
      parameters:
        - name: count
          in: query
          required: false
          description: Number of filings to return (max 40, requires auth for more than 5)
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 40
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Filing'
                  count:
                    type: integer
                  note:
                    type: string
                    description: Present on free preview responses only
              example:
                data:
                  - accession: "0001193125-26-142364"
                    company: "Goldman Sachs Private Credit Corp."
                    cik: "1920145"
                    filed: "2026-04-03"
                    items:
                      "7.01":
                        name: "Regulation FD Disclosure"
                        urgency: 1
                        urgency_label: "LOW"
                    max_urgency: 1
                    max_urgency_label: "LOW"
                    index_url: "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=1920145"
                count: 1
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/signals:
    get:
      summary: HIGH and CRITICAL Signals Only
      description: |
        Returns only filings with urgency >= 3 (HIGH or CRITICAL). Filters out LOW and MEDIUM events.

        | Level    | Score | Examples |
        |----------|-------|---------|
        | CRITICAL | 4     | Material impairments (2.06), Non-reliance on financials (4.02), Delisting notices (3.01) |
        | HIGH     | 3     | Agreement terminations (1.02), Layoffs (2.05), Auditor changes (4.01), Executive departures (5.02) |
      operationId: getSignals
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Filing'
                  count:
                    type: integer
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/filings/{accession}:
    get:
      summary: Single Filing Detail
      description: |
        Full filing detail for a specific accession number. Fetches the actual 8-K document
        from SEC EDGAR and extracts all items, dollar amounts, and 500-character context snippets.
      operationId: getFilingDetail
      security:
        - BearerAuth: []
      parameters:
        - name: accession
          in: path
          required: true
          description: SEC accession number in XXXXXXXXXX-YY-ZZZZZZ format
          schema:
            type: string
            pattern: '^\d{10}-\d{2}-\d{6}$'
          example: "0001193125-26-142364"
        - name: cik
          in: query
          required: false
          description: Company CIK. Required for filings not in recent 40. Speeds up lookup.
          schema:
            type: string
          example: "1920145"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilingDetail'
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Filing not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/company/{cik}:
    get:
      summary: Company Filing History
      description: Returns up to 20 most recent 8-K and 8-K/A filings for a company by CIK.
      operationId: getCompanyFilings
      security:
        - BearerAuth: []
      parameters:
        - name: cik
          in: path
          required: true
          description: Company CIK number (leading zeros optional)
          schema:
            type: string
          example: "1045810"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  cik:
                    type: integer
                    example: 1045810
                  name:
                    type: string
                    example: NVIDIA CORP
                  tickers:
                    type: array
                    items:
                      type: string
                    example: ["NVDA"]
                  recent_8ks:
                    type: array
                    items:
                      type: object
                      properties:
                        form:
                          type: string
                          enum: ["8-K", "8-K/A"]
                        filed:
                          type: string
                          format: date
                        accession:
                          type: string
                  count:
                    type: integer
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/subscribe:
    post:
      summary: Create Stripe Checkout Session
      description: |
        Creates a Stripe checkout session for API key subscription.
        No authentication required. After payment, the API key is emailed to the provided address.
      operationId: subscribe
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to receive the API key
                  example: you@example.com
                plan:
                  type: string
                  enum: [starter, unlimited]
                  default: starter
                  description: "starter: $29/mo (1000 req/day), unlimited: $99/mo"
      responses:
        '200':
          description: Checkout session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  checkout_url:
                    type: string
                    format: uri
                    description: Stripe checkout URL
                  plan:
                    type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /health:
    get:
      summary: Health Check
      description: Returns API status. No authentication required.
      operationId: healthCheck
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  service:
                    type: string
                    example: zhane-edgar-api
                  version:
                    type: string
                    example: 1.0.0

tags:
  - name: Filings
    description: SEC 8-K filing retrieval and parsing
  - name: Signals
    description: High-urgency event filtering
  - name: Companies
    description: Company-specific filing history
  - name: Subscriptions
    description: API key purchase
