openapi: 3.1.0
info:
  title: Rollbar Deployment Access Tokens RQL Jobs API
  description: The Rollbar Deployment API allows developers to notify Rollbar of application deployments and releases. By reporting deploys, teams can correlate error spikes with specific releases, track which code version introduced a bug, and automatically resolve items that were fixed in a deploy. The API accepts deployment metadata such as revision, environment, and rollbar_username, and integrates with CI/CD pipelines to provide continuous visibility into how deployments affect application stability.
  version: '1'
  contact:
    name: Rollbar Support
    url: https://rollbar.com/support/
  termsOfService: https://rollbar.com/terms/
servers:
- url: https://api.rollbar.com/api/1
  description: Production Server
security:
- accessToken: []
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.
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:
  schemas:
    RqlJobResponse:
      type: object
      properties:
        err:
          type: integer
          description: Error code. 0 indicates success.
        result:
          $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.
    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.
    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.
    RqlJobListResponse:
      type: object
      properties:
        err:
          type: integer
          description: Error code. 0 indicates success.
        result:
          type: array
          items:
            $ref: '#/components/schemas/RqlJob'
  parameters:
    JobIdParam:
      name: jobId
      in: path
      required: true
      description: The unique ID of the RQL job.
      schema:
        type: integer
  securitySchemes:
    accessToken:
      type: apiKey
      in: header
      name: X-Rollbar-Access-Token
      description: Rollbar access token for authentication. Requires write or post_server_item scope for creating deploys.
externalDocs:
  description: Rollbar Deployment API Documentation
  url: https://docs.rollbar.com/docs/deployment-api