Buildertrend Tasks API

Tasks on the jobs the linked user can see.

GitHub OpenAPI

Operations 4

GET /v1/tasks List tasks on one or more jobs #
POST /v1/tasks Create a task on a job #
GET /v1/tasks/{id} Get one task #
PATCH /v1/tasks/{id} Update a task #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/buildertrend:buildertrend-tasks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

buildertrend-tasks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Buildertrend Tasks API
  version: '1'
  description: 'Operations tagged Tasks across 2 of this provider''s published API definitions: buildertrend-open-api-reference.yml, buildertrend-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://developer.buildertrend.com/api
security:
- clientCredentials: []
tags:
- name: Tasks
  description: Tasks on the jobs the linked user can see.
paths:
  /v1/tasks:
    get:
      tags:
      - Tasks
      operationId: listTasks
      summary: List tasks on one or more jobs
      description: 'Tasks are read per job: take the job''s `id` from `GET /v1/jobs` and send it as

        `jobId`. `jobId` is required in practice: without it you get `200` with an empty `data` array.

        Many jobs have no tasks, so an empty list on its own proves nothing; to check an integration,

        use a job you can see has tasks in Buildertrend.

        A job the linked user can''t see returns `403`, the same as one that doesn''t exist.

        **A multi-job request is all-or-nothing**: one inaccessible id fails the whole request

        with `403`.'
      parameters:
      - name: jobId
        in: query
        description: 'The job to read: a job''s `id` from `GET /v1/jobs`. Repeat it to read several jobs at once. A value that isn''t a job ID is a `400`.'
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
        example:
        - 7d1e9c2a-5b3f-4e6d-8a9b-0c1d2e3f4a5b
      - name: taskType
        in: query
        required: false
        description: Restrict to these task types. Repeatable. Values are case-sensitive; an unknown value is a `400`, not ignored.
        schema:
          type: array
          items:
            type: string
            enum:
            - Task
            - PunchList
            - ScheduleItem
        style: form
        explode: true
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: A page of tasks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      tags:
      - Tasks
      operationId: createTask
      summary: Create a task on a job
      description: 'Creates a task on a job and returns it with the same fields as `GET /api/v1/tasks/{id}`,

        including `jobName`. The response carries a `Location` header pointing at that read.


        Every ID in the request is an external ID: `jobId` from `GET /api/v1/jobs`, `assignedToIds`

        from `GET /api/v1/jobs/{jobId}/users`, and `parentTaskId` from a task you''ve read.


        - **Subtasks.** Set `parentTaskId` to create a subtask. The parent must be a

        top-level task on the same job; a subtask can''t have its own subtasks.

        - **Assignees.** Each one must be on the job''s user list, the same people Buildertrend''s own

        assignee picker offers for that job. Anyone else is a `400` on `assignedToIds`.

        - **Dates and times.** Dates are `YYYY-MM-DD` and times are `HH:mm:ss`, both on the

        builder''s local clock, with no UTC offset. A task without times is all day. Five shapes

        are allowed:


        | Shape | `startDate` | `startTime` | `endDate` | `endTime` |

        | --- | --- | --- | --- | --- |

        | No dates | | | | |

        | Due date | | | set | |

        | Due date and time | | | set | set |

        | Date range, all day | set | | set | |

        | Date range with times | set | set | set | set |


        Anything else is a `400` naming the field. `endDate` can''t be before `startDate`, and on

        the same day `startTime` can''t be after `endTime`.


        The linked user needs permission to add tasks in Buildertrend. A job, parent task or

        assignee the linked user can''t see is `403`, the same as one that doesn''t exist.


        **There is no endpoint to delete a task.** Don''t retry a `5xx` blindly: the task may have

        been created anyway. Check the job''s tasks before you send the request again.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreateRequest'
      responses:
        '201':
          description: The task was created.
          headers:
            Location:
              description: The task's URL, e.g. `/api/v1/tasks/92802561-aeba-4a8d-afda-be53006d7c58`.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: A field is missing or invalid, `taskType` or `status` isn't a valid name, the parent task is on another job or is itself a subtask, or an assignee isn't on the job's user list. `errors` names each field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The linked user doesn't have permission to add tasks, or can't see the job, the parent task or an assignee. You can't tell "doesn't exist" from "not yours", by design.
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://developer.buildertrend.com/api
  /v1/tasks/{id}:
    get:
      tags:
      - Tasks
      operationId: getTask
      summary: Get one task
      description: 'Returns one task with the same fields as the list, with `jobName` filled in.


        Ids you can''t read don''t come back as `404`. A well-formed id that isn''t yours, or doesn''t

        exist, is `403`. Only a value that isn''t a GUID is `404`. The all-zero GUID returns `500`,

        a known platform bug.'
      parameters:
      - name: id
        in: path
        required: true
        description: The task's `id`.
        schema:
          type: string
          format: uuid
        example: 92802561-aeba-4a8d-afda-be53006d7c58
      responses:
        '200':
          description: The task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The id is not a GUID.
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      tags:
      - Tasks
      operationId: updateTask
      summary: Update a task
      description: 'Changes any of a task''s `title`, `taskType`, `status`, `startDate` and `endDate`, and returns

        the task with the same fields as `GET /api/v1/tasks/{id}`.


        Send only the fields you want to change; anything you leave out stays as it is. Send

        `startDate` or `endDate` as `null` to clear it. `title`, `taskType` and `status` can''t be

        cleared. Fields this request doesn''t take, like `id`, `jobId` or `parentTaskId`, are

        ignored, so the job, parent task and assignees stay as they are.


        - **Dates.** Dates only, sent as midnight with no UTC offset, e.g. `2026-01-12T00:00:00`. A

        time of day other than midnight is a `400`. After the change, a task with a `startDate`

        must still have an `endDate` that isn''t earlier. A task''s time of day isn''t part of this

        API: changing a date keeps it, and clearing a date clears it.

        - **Completing a task.** Setting `status` to `Completed` completes the task and leaves its

        subtasks as they are. A builder can require subtasks to be complete first; for that builder,

        completing a task with open subtasks is a `400` on `status`. The other fields are saved

        before the status, so check the task before you retry.


        The linked user needs permission to edit tasks in Buildertrend. A task the linked user can''t

        see is `403`, the same as one that doesn''t exist.'
      parameters:
      - name: id
        in: path
        required: true
        description: The task's `id`.
        schema:
          type: string
          format: uuid
        example: 92802561-aeba-4a8d-afda-be53006d7c58
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskUpdateRequest'
      responses:
        '200':
          description: The task, as saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Nothing to change was sent, a field is invalid, `taskType` or `status` isn't a valid name, the dates don't fit together, or the builder requires subtasks to be complete first and the task has open ones. `errors` names each field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The linked user doesn't have permission to edit tasks, or can't see the task. You can't tell "doesn't exist" from "not yours", by design.
        '404':
          description: The id is not a GUID.
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://developer.buildertrend.com/api
components:
  schemas:
    TaskUpdateRequest:
      type: object
      description: Send at least one field. Fields left out are unchanged.
      minProperties: 1
      properties:
        title:
          type: string
          maxLength: 255
          example: Frame inspection
        taskType:
          type: string
          enum:
          - Task
          - PunchList
          - ScheduleItem
          description: Case-sensitive.
          example: Task
        status:
          type: string
          enum:
          - NotStarted
          - Completed
          description: Case-sensitive.
          example: Completed
        startDate:
          type:
          - string
          - 'null'
          description: A date, as midnight with no UTC offset, e.g. `2026-01-12T00:00:00`. Send `null` to clear it.
          example: '2026-01-12T00:00:00'
        endDate:
          type:
          - string
          - 'null'
          description: A date, as midnight with no UTC offset. Send `null` to clear it, which you can't do while the task has a `startDate`.
          example: '2026-01-15T00:00:00'
    Pagination:
      type: object
      required:
      - limit
      - hasMore
      - nextCursor
      properties:
        limit:
          type: integer
          example: 50
        hasMore:
          type: boolean
          example: false
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass back as `cursor` while `hasMore` is true.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          example: api_key_not_linked
        message:
          type: string
    ValidationProblem:
      type: object
      properties:
        message:
          type: string
          example: One or more validation errors occurred.
        errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                description: The request field the error concerns.
                example: JobType
              message:
                type: string
                example: '''Spaceship'' is not a job type. Valid job types: Basement, Custom, Kitchen.'
    TaskCollection:
      type: object
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Task'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Task:
      type: object
      required:
      - id
      - title
      - taskType
      - status
      - jobId
      - jobName
      - startDate
      - startTime
      - endDate
      - endTime
      - parentTaskId
      - parentTaskName
      - isLocked
      - hasAttachments
      properties:
        id:
          type: string
          format: uuid
          example: 92802561-aeba-4a8d-afda-be53006d7c58
        title:
          type: string
          example: Frame inspection
        taskType:
          type: string
          enum:
          - Task
          - PunchList
          - ScheduleItem
          - Unknown
          description: '`Task`, `PunchList` or `ScheduleItem`. `Unknown` covers a type Buildertrend adds before this API names it.'
          example: Task
        status:
          type: string
          enum:
          - NotStarted
          - Completed
          - Unknown
          example: Completed
        jobId:
          type:
          - string
          - 'null'
          format: uuid
          description: The job's ID, as `GET /v1/jobs` lists it.
          example: 7d1e9c2a-5b3f-4e6d-8a9b-0c1d2e3f4a5b
        jobName:
          type:
          - string
          - 'null'
          description: '`null` in the list response; filled in on the single-task read.'
        startDate:
          type:
          - string
          - 'null'
          format: date
          example: '2026-01-12'
        startTime:
          type:
          - string
          - 'null'
          description: '`HH:mm:ss`, the builder''s local time. `null` for an all-day task.'
          example: 08:00:00
        endDate:
          type:
          - string
          - 'null'
          format: date
          description: The due date.
          example: '2026-01-15'
        endTime:
          type:
          - string
          - 'null'
          description: '`HH:mm:ss`, the builder''s local time. `null` for an all-day task.'
          example: '16:30:00'
        parentTaskId:
          type:
          - string
          - 'null'
          format: uuid
          description: '`null` for top-level tasks.'
        parentTaskName:
          type:
          - string
          - 'null'
          description: '`null` for top-level tasks.'
        isLocked:
          type: boolean
        hasAttachments:
          type: boolean
    TaskCreateRequest:
      type: object
      required:
      - title
      - jobId
      properties:
        title:
          type: string
          maxLength: 255
          example: Frame inspection
        jobId:
          type: string
          format: uuid
          description: The job's ID, as `GET /api/v1/jobs` lists it.
          example: 7d1e9c2a-5b3f-4e6d-8a9b-0c1d2e3f4a5b
        taskType:
          type: string
          enum:
          - Task
          - PunchList
          - ScheduleItem
          description: Case-sensitive. Defaults to `Task`.
          example: Task
        status:
          type: string
          enum:
          - NotStarted
          - Completed
          description: Case-sensitive. Defaults to `NotStarted`.
          example: NotStarted
        startDate:
          type: string
          format: date
          description: Set with `endDate` for a date range.
          example: '2026-01-12'
        startTime:
          type: string
          description: '`HH:mm:ss`, the builder''s local time. Needs `startDate`, `endDate` and `endTime`.'
          example: 08:00:00
        endDate:
          type: string
          format: date
          description: The due date. Required when any other date or time is set.
          example: '2026-01-15'
        endTime:
          type: string
          description: '`HH:mm:ss`, the builder''s local time. Needs `endDate`.'
          example: '16:30:00'
        parentTaskId:
          type: string
          format: uuid
          description: The parent task's `id`, to create a subtask. It must be a top-level task on the same job. Leave it out for a top-level task.
        assignedToIds:
          type: array
          description: Users to assign, by the `id` `GET /api/v1/jobs/{jobId}/users` lists. Each one must be on that list.
          items:
            type: string
            format: uuid
          example:
          - 0f1e2d3c-4b5a-4968-8776-5a4b3c2d1e0f
  responses:
    Unauthorized:
      description: '`missing_token` (no Bearer header), `invalid_token` (expired or wrong token), or `api_key_not_linked` (the token is fine, but the app has no linked Buildertrend account; see the linking step above).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The linked user can't see this job or record. You can't tell "doesn't exist" from "not yours", by design.
    BadRequest:
      description: A parameter is invalid, e.g. `limit` out of range or a malformed cursor.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationProblem'
    TooManyRequests:
      description: 'Rate limited: at most 60 requests per minute per app, counted across every endpoint. Back off and retry; don''t retry in a tight loop.'
  parameters:
    cursor:
      name: cursor
      in: query
      required: false
      description: '`pagination.nextCursor` from the previous page. Opaque: don''t parse, build or reuse one, and send the same filters with it. A malformed cursor is a `400`.'
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Page size, 1 to 200. A value outside that range is a `400`, not a silent clamp.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
  securitySchemes:
    clientCredentials:
      type: oauth2
      description: 'Exchange your app''s consumer key and secret at `POST /token`, then send the returned token as `Authorization: Bearer <token>`.'
      flows:
        clientCredentials:
          tokenUrl: /api/token
          scopes: {}
    consumerCredentials:
      type: http
      scheme: basic
      description: Consumer key as the username, consumer secret as the password.
x-refined-from:
- buildertrend-open-api-reference.yml
- buildertrend-openapi.yml