TestRail Projects API

openapi: 3.2.0
info:
  title: TestRail API (v2) Projects API
  description: TestRail is a web-based test case management and QA platform.
  version: '2.0'
  contact:
    name: TestRail (IDERA)
    url: https://www.testrail.com
  x-transport-note: The real request URL embeds the API version in a query string via index.php, e.g. https://example.testrail.io/index.php?/api/v2/get_run/1 - this is intentional and specific to TestRail, not a normal REST path.
servers:
- url: https://{instance}.testrail.io/index.php?/api/v2
  description: TestRail Cloud (per-instance host; replace {instance} with your subdomain)
  variables:
    instance:
      default: example
      description: Your TestRail Cloud subdomain.
- url: https://{host}/index.php?/api/v2
  description: TestRail Server / Enterprise (self-hosted; replace {host} with your install host)
  variables:
    host:
      default: testrail.example.com
      description: Hostname of your self-hosted TestRail installation.
security:
- basicAuth: []
tags:
- name: Projects
  description: Top-level containers owning suites, cases, runs, plans, and milestones.
paths:
  /get_projects:
    get:
      operationId: getProjects
      tags:
      - Projects
      summary: Get projects
      description: Returns the list of available projects.
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of projects.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /get_project/{project_id}:
    get:
      operationId: getProject
      tags:
      - Projects
      summary: Get project
      description: Returns an existing project by ID.
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: The requested project.
        '400':
          $ref: '#/components/responses/BadRequest'
  /add_project:
    post:
      operationId: addProject
      tags:
      - Projects
      summary: Add project
      description: Creates a new project (admin status required).
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          description: The created project.
        '403':
          $ref: '#/components/responses/Forbidden'
  /update_project/{project_id}:
    post:
      operationId: updateProject
      tags:
      - Projects
      summary: Update project
      description: Updates an existing project.
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          description: The updated project.
  /delete_project/{project_id}:
    post:
      operationId: deleteProject
      tags:
      - Projects
      summary: Delete project
      description: Deletes an existing project. This cannot be undone.
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Deletion confirmation.
components:
  requestBodies:
    GenericJson:
      required: true
      description: JSON request body. Field names follow the TestRail API reference for the specific method (see the method's support.testrail.com article).
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The ID of the project.
      schema:
        type: integer
    Limit:
      name: limit
      in: query
      required: false
      description: Number of records to return (1-250; bulk endpoints default and cap at 250).
      schema:
        type: integer
        minimum: 1
        maximum: 250
        default: 250
    Offset:
      name: offset
      in: query
      required: false
      description: Number of records to skip for pagination on bulk endpoints.
      schema:
        type: integer
        minimum: 0
  responses:
    BadRequest:
      description: Invalid or unknown identifier or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Authenticated user lacks permission (for example not an administrator).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid credentials (HTTP Basic).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message returned by TestRail.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication. Username is your TestRail email; password is your account password or an API key generated under My Settings. The API must be enabled by an admin under Administration > Site Settings > API.