openapi: 3.0.1
info:
  title: dbt Cloud Administrative API
  description: >-
    The dbt Cloud Administrative API enables programmatic administration of a dbt
    Cloud account. Use it to list and trigger jobs, poll and cancel runs, download
    run artifacts, and manage accounts, projects, and environments. This document
    models the documented v2 REST surface served from
    https://cloud.getdbt.com/api/v2. Requests are authenticated with a Bearer
    service token or personal access token. dbt Labs also offers a v3 REST API for
    additional resource management, a GraphQL Discovery (Metadata) API at
    metadata.cloud.getdbt.com/graphql, and a Semantic Layer API (GraphQL and JDBC).
  termsOfService: https://www.getdbt.com/cloud/terms
  contact:
    name: dbt Labs Support
    url: https://docs.getdbt.com/docs/dbt-cloud-apis/overview
  version: '2'
servers:
  - url: https://cloud.getdbt.com/api/v2
    description: dbt Cloud Administrative API v2 (multi-tenant North America). Account-specific
      regions use cloud.getdbt.com, emea.dbt.com, au.dbt.com, or a single-tenant host.
security:
  - BearerAuthentication: []
tags:
  - name: Accounts
    description: Account configuration and details.
  - name: Projects
    description: dbt projects within an account.
  - name: Jobs
    description: Job definitions and triggering of job runs.
  - name: Runs
    description: Job run history, status, and lifecycle.
  - name: Run Artifacts
    description: Artifacts (manifest, catalog, run results) produced by runs.
paths:
  /accounts/:
    get:
      operationId: listAccounts
      tags:
        - Accounts
      summary: List the accounts the authenticated token can access.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountListResponse'
  /accounts/{account_id}/:
    get:
      operationId: retrieveAccount
      tags:
        - Accounts
      summary: Retrieve a single account by ID.
      parameters:
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
  /accounts/{account_id}/projects/:
    get:
      operationId: listProjects
      tags:
        - Projects
      summary: List projects in an account.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectListResponse'
    post:
      operationId: createProject
      tags:
        - Projects
      summary: Create a project in an account.
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Project'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
  /accounts/{account_id}/projects/{id}/:
    get:
      operationId: retrieveProject
      tags:
        - Projects
      summary: Retrieve a project by ID.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
    post:
      operationId: updateProject
      tags:
        - Projects
      summary: Update a project by ID.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Project'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
    delete:
      operationId: destroyProject
      tags:
        - Projects
      summary: Delete a project by ID.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: OK
  /accounts/{account_id}/jobs/:
    get:
      operationId: listJobs
      tags:
        - Jobs
      summary: List jobs in an account, optionally filtered by project.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: project_id
          in: query
          schema:
            type: integer
          description: Filter jobs by project ID.
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
    post:
      operationId: createJob
      tags:
        - Jobs
      summary: Create a job in an account.
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Job'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
  /accounts/{account_id}/jobs/{id}/:
    get:
      operationId: retrieveJob
      tags:
        - Jobs
      summary: Retrieve a job by ID.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
    post:
      operationId: updateJob
      tags:
        - Jobs
      summary: Update a job by ID.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Job'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
    delete:
      operationId: destroyJob
      tags:
        - Jobs
      summary: Delete a job by ID.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: OK
  /accounts/{account_id}/jobs/{job_id}/run/:
    post:
      operationId: triggerJobRun
      tags:
        - Jobs
      summary: Trigger a job to run.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: job_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerRunRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
  /accounts/{account_id}/runs/:
    get:
      operationId: listRuns
      tags:
        - Runs
      summary: List runs in an account, with optional filtering and ordering.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: job_definition_id
          in: query
          schema:
            type: integer
          description: Filter runs by job ID.
        - name: order_by
          in: query
          schema:
            type: string
          description: Field to order results by (e.g. -id for most recent first).
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunListResponse'
  /accounts/{account_id}/runs/{id}/:
    get:
      operationId: retrieveRun
      tags:
        - Runs
      summary: Retrieve a run by ID.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/PathId'
        - name: include_related
          in: query
          schema:
            type: string
          description: 'Comma-separated related fields to include (e.g. trigger,job,run_steps).'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
  /accounts/{account_id}/runs/{run_id}/cancel/:
    post:
      operationId: cancelRun
      tags:
        - Runs
      summary: Cancel a run that is queued or in progress.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: run_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
  /accounts/{account_id}/runs/{run_id}/artifacts/:
    get:
      operationId: listRunArtifacts
      tags:
        - Run Artifacts
      summary: List artifact files generated by a completed run.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: run_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactListResponse'
  /accounts/{account_id}/runs/{run_id}/artifacts/{path}:
    get:
      operationId: retrieveRunArtifact
      tags:
        - Run Artifacts
      summary: Download a specific artifact file (e.g. manifest.json, catalog.json) from a run.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: run_id
          in: path
          required: true
          schema:
            type: integer
        - name: path
          in: path
          required: true
          schema:
            type: string
          description: 'Relative artifact path, e.g. manifest.json or run_results.json.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
components:
  securitySchemes:
    BearerAuthentication:
      type: http
      scheme: bearer
      description: >-
        dbt Cloud service token or personal access token passed in the
        Authorization header as 'Authorization: Token <token>' or
        'Authorization: Bearer <token>'.
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      schema:
        type: integer
      description: Numeric dbt Cloud account ID.
    PathId:
      name: id
      in: path
      required: true
      schema:
        type: integer
      description: Numeric resource ID.
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        maximum: 100
      description: Maximum number of results to return (max 100).
    Offset:
      name: offset
      in: query
      schema:
        type: integer
      description: Number of results to skip for pagination.
  schemas:
    Pagination:
      type: object
      properties:
        count:
          type: integer
        total_count:
          type: integer
    StatusMeta:
      type: object
      properties:
        code:
          type: integer
        is_success:
          type: boolean
        user_message:
          type: string
        developer_message:
          type: string
    Account:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        plan:
          type: string
        state:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    AccountResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          $ref: '#/components/schemas/Account'
    AccountListResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Account'
    Project:
      type: object
      properties:
        id:
          type: integer
        account_id:
          type: integer
        name:
          type: string
        connection_id:
          type: integer
        repository_id:
          type: integer
        state:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ProjectResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          $ref: '#/components/schemas/Project'
    ProjectListResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Project'
        extra:
          type: object
          properties:
            pagination:
              $ref: '#/components/schemas/Pagination'
    JobSettings:
      type: object
      properties:
        threads:
          type: integer
        target_name:
          type: string
    JobTriggers:
      type: object
      properties:
        github_webhook:
          type: boolean
        git_provider_webhook:
          type: boolean
        schedule:
          type: boolean
        on_merge:
          type: boolean
    Job:
      type: object
      properties:
        id:
          type: integer
        account_id:
          type: integer
        project_id:
          type: integer
        environment_id:
          type: integer
        name:
          type: string
        description:
          type: string
        execute_steps:
          type: array
          items:
            type: string
        dbt_version:
          type: string
        state:
          type: integer
        triggers:
          $ref: '#/components/schemas/JobTriggers'
        settings:
          $ref: '#/components/schemas/JobSettings'
        schedule:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    JobResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          $ref: '#/components/schemas/Job'
    JobListResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Job'
        extra:
          type: object
          properties:
            pagination:
              $ref: '#/components/schemas/Pagination'
    TriggerRunRequest:
      type: object
      required:
        - cause
      properties:
        cause:
          type: string
          description: Human-readable reason the run was triggered.
        git_sha:
          type: string
        git_branch:
          type: string
        schema_override:
          type: string
        dbt_version_override:
          type: string
        threads_override:
          type: integer
        steps_override:
          type: array
          items:
            type: string
    Run:
      type: object
      properties:
        id:
          type: integer
        account_id:
          type: integer
        project_id:
          type: integer
        job_definition_id:
          type: integer
        environment_id:
          type: integer
        status:
          type: integer
          description: '1=Queued, 2=Starting, 3=Running, 10=Success, 20=Error, 30=Cancelled.'
        status_humanized:
          type: string
        git_branch:
          type: string
        git_sha:
          type: string
        is_complete:
          type: boolean
        is_success:
          type: boolean
        is_error:
          type: boolean
        is_cancelled:
          type: boolean
        href:
          type: string
        created_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
    RunResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          $ref: '#/components/schemas/Run'
    RunListResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Run'
        extra:
          type: object
          properties:
            pagination:
              $ref: '#/components/schemas/Pagination'
    ArtifactListResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          type: array
          items:
            type: string
          description: Relative paths of artifact files available for download.