roic-ai Calendar API

openapi: 3.2.0
info:
  title: ROIC Calendar API
  description: The ROIC API reference for v3 (`/v3.0.0`) and legacy v2 (`/v2`). In v3, Bearer authentication is recommended because it keeps credentials out of URLs. For browser testing, you may instead pass your key as the `apikey` query parameter. Use exactly one authentication method per request, never both. v2 takes the key only as the `apikey` query parameter.
  version: 3.0.0
servers:
- url: https://api.roic.ai
tags:
- name: Calendar
  description: Dated company event resources such as the earnings calendar.
paths:
  /v3.0.0/calendar/earnings:
    get:
      operationId: listEarningsCalendar
      summary: List earnings calendar events
      description: Returns a page of dated earnings events across all tickers, or one ticker via the identifier filter. Each event carries the scheduled release date and session plus EPS and revenue estimates, actuals, and surprises.
      tags:
      - Calendar
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: apikey
        in: query
        required: false
        schema:
          description: Browser-friendly alternative to Bearer authentication. Use either this parameter or the Authorization header, never both.
          type: string
      - name: identifier
        in: query
        required: false
        schema:
          minLength: 1
          maxLength: 128
          title: identifier
          description: Restrict results to a single ticker. Accepts an exchange and symbol separated by a colon (e.g. `NASDAQ:AAPL`), a ticker ID, or a FIGI. Omit to list earnings events across all tickers.
          examples:
          - NASDAQ:AAPL
          - tkr_cO46h8pgSu9Qqy
          - BBG000B9XRY4
          type: string
      - name: date
        in: query
        required: false
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: Return events whose release date is exactly this date.
          type: string
      - name: date.gte
        in: query
        required: false
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: Return events whose release date is on or after this date.
          type: string
      - name: date.gt
        in: query
        required: false
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: Return events whose release date is strictly after this date.
          type: string
      - name: date.lte
        in: query
        required: false
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: Return events whose release date is on or before this date.
          type: string
      - name: date.lt
        in: query
        required: false
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: Return events whose release date is strictly before this date.
          type: string
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: limit
        in: query
        required: false
        schema:
          minimum: 1
          maximum: 500
          multipleOf: 1
          default: 100
          title: limit
          description: Maximum number of resources to return. Defaults to 100.
          anyOf:
          - format: numeric
            default: 0
            type: string
          - minimum: 1
            maximum: 500
            multipleOf: 1
            default: 100
            title: limit
            description: Maximum number of resources to return. Defaults to 100.
            type: number
      - name: page
        in: query
        required: false
        schema:
          maxLength: 4096
          description: Opaque page token from a previous response. Prefer following the returned page URLs directly.
          type: string
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.EarningsEventList'
        '400':
          description: Response for status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '401':
          description: Response for status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '402':
          description: Response for status 402
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '404':
          description: Response for status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '429':
          description: Response for status 429
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '500':
          description: Response for status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '503':
          description: Response for status 503
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
      x-fern-sdk-group-name: calendar.earnings
      x-fern-sdk-method-name: list
components:
  schemas:
    v3.Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - invalid_request_error
              - authentication_error
              - payment_required_error
              - conflict_error
              - rate_limit_error
              - api_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
            doc_url:
              type: string
            request_id:
              type: string
          required:
          - type
          - code
          - message
          - request_id
      required:
      - error
      $id: '#/components/schemas/v3.Error'
    v3.EarningsEventList:
      additionalProperties: false
      type: object
      properties:
        data:
          type: array
          items:
            additionalProperties: false
            type: object
            properties:
              id:
                type: string
              object:
                const: v3.calendar.earnings_event
                type: string
              symbol:
                type: string
              exchange:
                type: string
              period_end_date:
                pattern: ^\d{4}-\d{2}-\d{2}$
                minLength: 10
                maxLength: 10
                description: A calendar date in YYYY-MM-DD format.
                type: string
              fiscal_period:
                anyOf:
                - type: string
                - type: 'null'
              release_date:
                pattern: ^\d{4}-\d{2}-\d{2}$
                minLength: 10
                maxLength: 10
                description: A calendar date in YYYY-MM-DD format.
                type: string
              release_time:
                anyOf:
                - format: date-time
                  type: string
                - type: 'null'
              release_session:
                anyOf:
                - const: pre-market
                  type: string
                - const: post-market
                  type: string
                - type: 'null'
              is_confirmed:
                type: boolean
              is_reported:
                type: boolean
              eps_actual:
                anyOf:
                - type: number
                - type: 'null'
              eps_estimate:
                anyOf:
                - type: number
                - type: 'null'
              eps_surprise:
                anyOf:
                - type: number
                - type: 'null'
              eps_surprise_percent:
                anyOf:
                - type: number
                - type: 'null'
              revenue_actual:
                anyOf:
                - type: number
                - type: 'null'
              revenue_estimate:
                anyOf:
                - type: number
                - type: 'null'
              revenue_surprise:
                anyOf:
                - type: number
                - type: 'null'
              revenue_surprise_percent:
                anyOf:
                - type: number
                - type: 'null'
              currency:
                type: string
              updated_at:
                format: date-time
                type: string
            required:
            - id
            - object
            - symbol
            - exchange
            - period_end_date
            - fiscal_period
            - release_date
            - release_time
            - release_session
            - is_confirmed
            - is_reported
            - eps_actual
            - eps_estimate
            - eps_surprise
            - eps_surprise_percent
            - revenue_actual
            - revenue_estimate
            - revenue_surprise
            - revenue_surprise_percent
            - currency
            - updated_at
            $id: '#/components/schemas/v3.EarningsEvent'
        next_page_url:
          anyOf:
          - type: string
          - type: 'null'
        previous_page_url:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - data
      - next_page_url
      - previous_page_url
      $id: '#/components/schemas/v3.EarningsEventList'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Recommended. Send your ROIC API key as a Bearer token.
    apiKeyAuth:
      type: apiKey
      in: query
      name: apikey
      description: Browser-friendly alternative. Do not combine this query parameter with the Authorization header.