openapi: 3.1.0
info:
  title: Rollbar RQL API
  description: >-
    The Rollbar RQL (Rollbar Query Language) API provides a SQL-like interface
    for querying error and deployment data stored in Rollbar. It supports
    SELECT queries against two logical tables: item_occurrence and deploy,
    allowing developers to perform complex filtering, grouping, and analysis
    of error data. RQL jobs can be submitted and retrieved via the API,
    enabling programmatic access to advanced analytics that go beyond the
    standard REST API capabilities. Jobs will timeout after 10 minutes of
    running.
  version: '1'
  contact:
    name: Rollbar Support
    url: https://rollbar.com/support/
  termsOfService: https://rollbar.com/terms/
externalDocs:
  description: Rollbar RQL Documentation
  url: https://docs.rollbar.com/docs/rql
servers:
  - url: https://api.rollbar.com/api/1
    description: Production Server
tags:
  - name: RQL Jobs
    description: >-
      Submit, list, and retrieve results for RQL (Rollbar Query Language) jobs.
      RQL provides a SQL-like interface for querying error and deployment data.
security:
  - accessToken: []
paths:
  /rql/jobs/:
    get:
      operationId: listRqlJobs
      summary: List All RQL Jobs
      description: >-
        Returns all RQL jobs for the project, including their status
        and query details.
      tags:
        - RQL Jobs
      responses:
        '200':
          description: List of RQL jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RqlJobListResponse'
        '401':
          description: Unauthorized
    post:
      operationId: createRqlJob
      summary: Create an RQL Job
      description: >-
        Submits a new RQL query as a job. The query uses a SQL-like syntax
        and can query the item_occurrence and deploy logical tables. Jobs
        run asynchronously and will timeout after 10 minutes.
      tags:
        - RQL Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRqlJobRequest'
      responses:
        '200':
          description: RQL job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RqlJobResponse'
        '400':
          description: Bad request - invalid query syntax
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
  /rql/job/{jobId}:
    get:
      operationId: getRqlJob
      summary: Get an RQL Job
      description: >-
        Returns information about a specific RQL job, including its
        current status and query details.
      tags:
        - RQL Jobs
      parameters:
        - $ref: '#/components/parameters/JobIdParam'
      responses:
        '200':
          description: RQL job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RqlJobResponse'
        '401':
          description: Unauthorized
        '404':
          description: Job not found
  /rql/job/{jobId}/result:
    get:
      operationId: getRqlJobResults
      summary: Get RQL Job Results
      description: >-
        Returns the results of a completed RQL job. The job must be in
        the success status. Results include column definitions and rows
        of data matching the query.
      tags:
        - RQL Jobs
      parameters:
        - $ref: '#/components/parameters/JobIdParam'
      responses:
        '200':
          description: RQL job results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RqlJobResultResponse'
        '401':
          description: Unauthorized
        '404':
          description: Job not found
        '422':
          description: Job has not completed successfully
components:
  securitySchemes:
    accessToken:
      type: apiKey
      in: header
      name: X-Rollbar-Access-Token
      description: >-
        Rollbar access token with read scope for authentication.
  parameters:
    JobIdParam:
      name: jobId
      in: path
      required: true
      description: >-
        The unique ID of the RQL job.
      schema:
        type: integer
  schemas:
    RqlJob:
      type: object
      description: >-
        An RQL job representing a submitted query.
      properties:
        id:
          type: integer
          description: >-
            The RQL job ID.
        project_id:
          type: integer
          description: >-
            The project ID this job belongs to.
        query_string:
          type: string
          description: >-
            The RQL query string that was submitted.
        status:
          type: string
          description: >-
            The current status of the job.
          enum:
            - new
            - running
            - success
            - failed
            - cancelled
            - timed_out
        job_hash:
          type: string
          description: >-
            A hash identifying duplicate queries.
        date_created:
          type: integer
          description: >-
            Unix timestamp when the job was created.
        date_modified:
          type: integer
          description: >-
            Unix timestamp when the job was last updated.
    CreateRqlJobRequest:
      type: object
      description: >-
        Request body for creating a new RQL job.
      required:
        - query_string
      properties:
        query_string:
          type: string
          description: >-
            The RQL query to execute. Supports SELECT queries against
            the item_occurrence and deploy tables with WHERE, GROUP BY,
            ORDER BY, and LIMIT clauses.
        force_refresh:
          type: boolean
          description: >-
            Whether to force a fresh query instead of using cached results.
    RqlJobResponse:
      type: object
      properties:
        err:
          type: integer
          description: >-
            Error code. 0 indicates success.
        result:
          $ref: '#/components/schemas/RqlJob'
    RqlJobListResponse:
      type: object
      properties:
        err:
          type: integer
          description: >-
            Error code. 0 indicates success.
        result:
          type: array
          items:
            $ref: '#/components/schemas/RqlJob'
    RqlJobResultResponse:
      type: object
      properties:
        err:
          type: integer
          description: >-
            Error code. 0 indicates success.
        result:
          type: object
          properties:
            columns:
              type: array
              description: >-
                Column names from the query result.
              items:
                type: string
            rows:
              type: array
              description: >-
                Rows of data matching the query. Each row is an array
                of values corresponding to the columns.
              items:
                type: array
                items: {}
            rowcount:
              type: integer
              description: >-
                Total number of rows in the result.
            selectionCondition:
              type: string
              description: >-
                The parsed selection condition from the query.