openapi: "3.0.3"
info:
  title: Sentinela API
  description: |
    Brazilian Financial Data API — Real-time market data from BCB and CVM.

    ## API Plans
    - **Free** ($0): 30 req/min, market data only, no API key needed
    - **Bronze** ($29/mo): 100 req/min, + companies & search
    - **Gold** ($99/mo): 500 req/min, all data including filings & bulk export
    - **Platinum** ($299/mo): 2000 req/min, all data + webhooks, priority support, CSV export

    Include your API key via `X-API-Key` header or `Authorization: Bearer <key>`.
  version: 0.3.0
  contact:
    name: Sentinela
    url: https://git.ophion.com.br/rainbow/sentinela-go
  license:
    name: MIT

servers:
  - url: /
    description: Current server

tags:
  - name: Plans
    description: API plan management, registration, and usage
  - name: Health
    description: Health check
  - name: Companies
    description: CVM registered companies
  - name: Filings
    description: CVM company filings
  - name: Market Data
    description: BCB market rates and indicators
  - name: Search
    description: Global search across all entities

paths:
  /health:
    get:
      tags: [Health]
      summary: Health check
      description: Returns API health status
      responses:
        "200":
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                    example: "0.2.0"

  /api/v1/companies:
    get:
      tags: [Companies]
      summary: List companies
      description: Returns a paginated list of CVM registered companies
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          description: Number of results to return
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Offset for pagination
        - name: status
          in: query
          schema:
            type: string
          description: Filter by registration status
        - name: sector
          in: query
          schema:
            type: string
          description: Filter by sector
      responses:
        "200":
          description: List of companies
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Company"
                  total:
                    type: integer
                    example: 842
                  limit:
                    type: integer
                    example: 20
                  offset:
                    type: integer
                    example: 0
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/companies/search:
    get:
      tags: [Companies]
      summary: Search companies
      description: Full-text search across company names and documents
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
          example: Petrobras
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Company"
                  total:
                    type: integer
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/companies/{id}:
    get:
      tags: [Companies]
      summary: Get company by ID
      description: Returns a single company by its CVM code
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Company CVM code
      responses:
        "200":
          description: Company details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Company"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/companies/{id}/filings:
    get:
      tags: [Companies]
      summary: Get company filings
      description: Returns all filings for a specific company
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Company CVM code
      responses:
        "200":
          description: List of filings for the company
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Filing"
                  total:
                    type: integer
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/filings:
    get:
      tags: [Filings]
      summary: List filings
      description: Returns a paginated list of CVM filings
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: category
          in: query
          schema:
            type: string
          description: Filter by filing category
        - name: from
          in: query
          schema:
            type: string
            format: date
          description: Start date (YYYY-MM-DD)
        - name: to
          in: query
          schema:
            type: string
            format: date
          description: End date (YYYY-MM-DD)
      responses:
        "200":
          description: List of filings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Filing"
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/filings/search:
    get:
      tags: [Filings]
      summary: Search filings
      description: Full-text search across filings
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          example: fato relevante
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Filing"
                  total:
                    type: integer
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/filings/recent:
    get:
      tags: [Filings]
      summary: Recent filings
      description: Returns the most recent CVM filings
      responses:
        "200":
          description: Recent filings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Filing"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/filings/{id}:
    get:
      tags: [Filings]
      summary: Get filing by ID
      description: Returns a single filing by its ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Filing details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Filing"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/market/selic:
    get:
      tags: [Market Data]
      summary: Selic rate history
      description: Returns historical Selic (Brazil's base interest rate) data from BCB
      parameters:
        - $ref: "#/components/parameters/from"
        - $ref: "#/components/parameters/to"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: Selic rate history
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Rate"
              example:
                data:
                  - date: "2025-01-29"
                    value: 15.0
                  - date: "2025-01-28"
                    value: 15.0
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/market/selic/current:
    get:
      tags: [Market Data]
      summary: Current Selic rate
      description: Returns the current Selic rate
      responses:
        "200":
          description: Current Selic rate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Rate"
              example:
                date: "2025-01-29"
                value: 15.0
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/market/cdi:
    get:
      tags: [Market Data]
      summary: CDI rate history
      description: Returns historical CDI (interbank deposit rate) data
      parameters:
        - $ref: "#/components/parameters/from"
        - $ref: "#/components/parameters/to"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: CDI rate history
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Rate"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/market/cdi/current:
    get:
      tags: [Market Data]
      summary: Current CDI rate
      description: Returns the current CDI rate
      responses:
        "200":
          description: Current CDI rate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Rate"
              example:
                date: "2025-01-29"
                value: 14.9
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/market/ipca:
    get:
      tags: [Market Data]
      summary: IPCA inflation history
      description: Returns historical IPCA (Brazilian consumer price index) data
      parameters:
        - $ref: "#/components/parameters/from"
        - $ref: "#/components/parameters/to"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: IPCA history
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Rate"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/market/ipca/current:
    get:
      tags: [Market Data]
      summary: Current IPCA rate
      description: Returns the latest IPCA monthly rate
      responses:
        "200":
          description: Current IPCA rate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Rate"
              example:
                date: "2025-01-01"
                value: 0.52
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/market/fx:
    get:
      tags: [Market Data]
      summary: FX rate history
      description: Returns historical foreign exchange rate data
      parameters:
        - name: pair
          in: query
          schema:
            type: string
            default: USD/BRL
          description: Currency pair (e.g., USD/BRL, EUR/BRL)
        - $ref: "#/components/parameters/from"
        - $ref: "#/components/parameters/to"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: FX rate history
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/FXRate"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/market/fx/current:
    get:
      tags: [Market Data]
      summary: Current FX rate
      description: Returns the current foreign exchange rate
      responses:
        "200":
          description: Current FX rate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FXRate"
              example:
                date: "2025-01-29"
                pair: USD/BRL
                buy: 5.19
                sell: 5.20
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/market/overview:
    get:
      tags: [Market Data]
      summary: Market overview
      description: Returns a snapshot of all key market indicators
      responses:
        "200":
          description: Market overview
          content:
            application/json:
              schema:
                type: object
                properties:
                  selic:
                    $ref: "#/components/schemas/Rate"
                  cdi:
                    $ref: "#/components/schemas/Rate"
                  ipca:
                    $ref: "#/components/schemas/Rate"
                  fx:
                    $ref: "#/components/schemas/FXRate"
              example:
                selic:
                  date: "2025-01-29"
                  value: 15.0
                cdi:
                  date: "2025-01-29"
                  value: 14.9
                ipca:
                  date: "2025-01-01"
                  value: 0.52
                fx:
                  date: "2025-01-29"
                  pair: USD/BRL
                  buy: 5.19
                  sell: 5.20
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/plans:
    get:
      tags: [Plans]
      summary: List available plans
      description: Returns all available API plans with pricing and features
      responses:
        "200":
          description: List of plans
          content:
            application/json:
              schema:
                type: object
                properties:
                  plans:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        price:
                          type: number
                        currency:
                          type: string
                        rate_limit:
                          type: integer
                        features:
                          type: array
                          items:
                            type: string
                        restrictions:
                          type: array
                          items:
                            type: string

  /api/v1/plans/usage:
    get:
      tags: [Plans]
      summary: Get usage stats
      description: Returns usage statistics for the authenticated API key
      security:
        - ApiKeyAuth: []
      parameters:
        - name: from
          in: query
          schema:
            type: string
            format: date
          description: Start date (YYYY-MM-DD)
        - name: to
          in: query
          schema:
            type: string
            format: date
          description: End date (YYYY-MM-DD)
      responses:
        "200":
          description: Usage statistics
        "401":
          description: API key required

  /api/v1/plans/register:
    post:
      tags: [Plans]
      summary: Register for free tier
      description: Create a new API key on the free plan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, email]
              properties:
                name:
                  type: string
                  example: "John Doe"
                email:
                  type: string
                  format: email
                  example: "john@example.com"
      responses:
        "201":
          description: API key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  api_key:
                    type: string
                  plan:
                    type: string
                  rate_limit:
                    type: integer
        "400":
          $ref: "#/components/responses/BadRequest"

  /api/v1/search:
    get:
      tags: [Search]
      summary: Global search
      description: Search across companies, filings, and market data
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
          example: Petrobras
      responses:
        "200":
          description: Search results grouped by type
          content:
            application/json:
              schema:
                type: object
                properties:
                  companies:
                    type: array
                    items:
                      $ref: "#/components/schemas/Company"
                  filings:
                    type: array
                    items:
                      $ref: "#/components/schemas/Filing"
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimited"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authenticated access. Free tier works without a key.

  parameters:
    from:
      name: from
      in: query
      schema:
        type: string
        format: date
      description: Start date (YYYY-MM-DD)
    to:
      name: to
      in: query
      schema:
        type: string
        format: date
      description: End date (YYYY-MM-DD)
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
      description: Number of results to return

  schemas:
    Company:
      type: object
      properties:
        id:
          type: string
          example: "9512"
        name:
          type: string
          example: "PETRÓLEO BRASILEIRO S.A. - PETROBRAS"
        cnpj:
          type: string
          example: "33.000.167/0001-01"
        status:
          type: string
          example: "ATIVO"
        sector:
          type: string
          example: "Petróleo, Gás e Biocombustíveis"

    Filing:
      type: object
      properties:
        id:
          type: string
          example: "123456"
        company_id:
          type: string
          example: "9512"
        company_name:
          type: string
          example: "PETRÓLEO BRASILEIRO S.A. - PETROBRAS"
        category:
          type: string
          example: "Fato Relevante"
        date:
          type: string
          format: date-time
          example: "2025-01-29T18:30:00Z"
        description:
          type: string
          example: "Descoberta de novo campo no pré-sal"

    Rate:
      type: object
      properties:
        date:
          type: string
          format: date
          example: "2025-01-29"
        value:
          type: number
          format: double
          example: 15.0

    FXRate:
      type: object
      properties:
        date:
          type: string
          format: date
          example: "2025-01-29"
        pair:
          type: string
          example: "USD/BRL"
        buy:
          type: number
          format: double
          example: 5.19
        sell:
          type: number
          format: double
          example: 5.20

    Error:
      type: object
      properties:
        error:
          type: string
          example: "invalid request"
        message:
          type: string
          example: "missing required parameter: q"

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: bad_request
            message: "missing required parameter: q"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: not_found
            message: "resource not found"
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: rate_limited
            message: "too many requests"