Every API here is available over the APIs.io API and to AI agents over MCP.
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