> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/projects.md).

# Projects

One-off installation and construction work.

A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.

Fields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project).

## List projects

> Projects, newest first, optionally for one customer or matching words in the name or reference.\
> \
> Returns a list of \[project objects]\(<https://docs.shortcutco.com/developers/reference/objects/project>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The project's id."},"object":{"type":"string","const":"project","description":"Always `project`."},"name":{"type":"string","description":"Its name."},"reference":{"type":["string","null"],"description":"The workspace's reference for it."},"customerPoNumber":{"type":["string","null"],"description":"The customer's purchase order number."},"stage":{"type":"string","description":"Where it stands, e.g. `draft`, `estimating`, `in_progress`, `complete`."},"customerId":{"type":"string","format":"uuid","description":"The customer it is for."},"customerName":{"type":"string","description":"The customer's name."},"onHold":{"type":"boolean","description":"Whether it is on hold."},"holdResumeDate":{"type":["string","null"],"description":"When a hold ends, `YYYY-MM-DD`."},"createdAt":{"type":"string","format":"date-time","description":"When it was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","name","reference","customerPoNumber","stage","customerId","customerName","onHold","holdResumeDate","createdAt","updatedAt"],"additionalProperties":false,"description":"A project: one-off construction or installation work with phases and change orders."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects":{"get":{"operationId":"projects.list","tags":["Projects"],"summary":"List projects","description":"Projects, newest first, optionally for one customer or matching words in the name or reference.\n\nReturns a list of [project objects](https://docs.shortcutco.com/developers/reference/objects/project).","parameters":[{"name":"limit","in":"query","required":false,"description":"How many items to return, 1-200. Defaults to 50.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The `meta.nextCursor` from the previous page. Omit it for the first page.","schema":{"type":"string","minLength":1,"maxLength":4096}},{"name":"customerId","in":"query","required":false,"description":"Only this customer's projects.","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","required":false,"description":"Words in the project's name or reference.","schema":{"type":"string","minLength":1,"maxLength":120}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"meta":{"type":"object","properties":{"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean","description":"Whether another page exists."}},"required":["nextCursor","hasMore"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Create a draft project

> Creates a draft project for a customer (\`customerId\`) or from a lead (\`leadId\`), as New project does in the app: the project starts in Draft with its first estimate revision and one unnamed phase. Add phases with \`POST /v1/projects/{id}/estimate/phases\` and lines with \`POST /v1/projects/{id}/estimate/lines\`; the answer is the empty estimate with the project's \`version\`, which each change sends back as \`expectedVersion\`. Nothing is sent to the customer, and no API call sends, approves, signs or bills a project: a person does that in Shortcut at \`appUrl\`. The workspace needs a default sales-tax rate in Settings > Projects. With \`leadId\`, the lead becomes a prospect linked to its customer account, as in the app, and workspace automations on that change may react if the token has \`automations:trigger\`. Send an \`Idempotency-Key\` to retry safely.\
> \
> Returns \[the project estimate object]\(<https://docs.shortcutco.com/developers/reference/objects/project-estimate).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`project\_estimate\_edit\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_estimate\\_edit\\_not\\_allowed>), \[\`projects\_read\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#projects\\_read\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>), \[\`version\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#version\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"ProjectEstimate":{"type":"object","properties":{"object":{"type":"string","const":"project_estimate","description":"Always `project_estimate`."},"projectId":{"type":"string","format":"uuid","description":"The project's id."},"version":{"type":"integer","description":"The project's version. Send it as `expectedVersion` with the next change."},"name":{"type":"string","description":"The project's name."},"reference":{"type":["string","null"],"description":"The project's reference, such as a bid number."},"stage":{"type":"string","description":"The project's stage: `draft` until a person sends the estimate."},"customerId":{"type":"string","format":"uuid","description":"The customer the project is for."},"estimateId":{"type":"string","format":"uuid","description":"The estimate revision's id."},"revisionNumber":{"type":"integer","description":"Which revision of the estimate this is; 1 on a new project."},"status":{"type":"string","description":"The estimate revision's status. Only a `draft` can be changed."},"editable":{"type":"boolean","description":"Whether the estimate can be changed through the API: true while it is a draft."},"appUrl":{"type":"string","description":"Where a person opens this estimate in Shortcut to review and send it."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimatePhase"},"description":"The estimate's phases, in order."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimateLine"},"description":"The estimate's lines, in order."},"totals":{"type":"object","properties":{"subtotal":{"type":"number","description":"The sum of the lines' prices, in US dollars."},"discountAmount":{"type":"number","description":"The discount a person set in the app, in US dollars; 0 without one."},"preTaxTotal":{"type":"number","description":"The subtotal less the discount."},"taxRatePct":{"type":"number","description":"The project's sales-tax rate, in percent."},"tax":{"type":"number","description":"Sales tax on the taxable lines, in US dollars."},"total":{"type":"number","description":"What the customer would pay, in US dollars. A `tm` phase's part is an estimate, not a final bill."}},"required":["subtotal","discountAmount","preTaxTotal","taxRatePct","tax","total"],"additionalProperties":false,"description":"The estimate's totals, computed by the app."}},"required":["object","projectId","version","name","reference","stage","customerId","estimateId","revisionNumber","status","editable","appUrl","phases","lines","totals"],"additionalProperties":false,"description":"A project's current estimate with its phases, lines and totals. Sell side only: cost, markup and margin are never part of it."},"ProjectEstimatePhase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The phase's id."},"name":{"type":"string","description":"The phase's name."},"placeholder":{"type":"boolean","description":"True for the one unnamed phase a new project starts with; the app hides it until a second phase exists. The first phase you add takes its place while it is empty and untouched."},"workType":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"],"description":"The kind of work."},"billingMode":{"type":"string","enum":["fixed","tm"],"description":"`fixed`: sold at the sum of its lines. `tm`: time and materials, billed by the hour."},"tmRatePerHour":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's hourly rate in US dollars."},"tmEstimatedHours":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's estimated hours."},"tmLaborTaxable":{"type":["boolean","null"],"description":"Whether a `tm` phase's labor is taxed; null on a phase that was never `tm`."},"plannedTeamSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many people the phase is planned for."},"laborHours":{"type":"number","description":"Labor hours the phase's lines add up to."},"lineCount":{"type":"integer","description":"How many lines the phase has."},"priceTotal":{"type":"number","description":"The phase's price before discount and tax, in US dollars."}},"required":["id","name","placeholder","workType","billingMode","tmRatePerHour","tmEstimatedHours","tmLaborTaxable","plannedTeamSize","laborHours","lineCount","priceTotal"],"additionalProperties":false,"description":"One phase of a project's estimate."},"ProjectEstimateLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The line's id."},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The phase the line is in."},"name":{"type":"string","description":"The line's name."},"description":{"type":["string","null"],"description":"Shown under the line."},"kind":{"type":"string","enum":["material","labor","equipment","other"],"description":"`material`, `labor`, `equipment`, or `other`."},"quantity":{"type":"number","description":"Units sold. On a labor line with a production rate, the hours worked out from `measuredQuantity`."},"measuredQuantity":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"On a labor line with a production rate, the measured amount the hours come from (640 sq ft); null otherwise."},"unit":{"type":["string","null"],"description":"The unit the quantity counts, such as `sq ft` or `h`."},"unitPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"What one unit sells for, in US dollars."},"price":{"type":"number","description":"The line's price, in US dollars."},"taxable":{"type":"boolean","description":"Whether sales tax applies to the line."},"priceBookItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The price-book item the line was picked from; null on a typed-in line."}},"required":["id","phaseId","name","description","kind","quantity","measuredQuantity","unit","unitPrice","price","taxable","priceBookItemId"],"additionalProperties":false,"description":"One line of a project's estimate."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects":{"post":{"operationId":"projects.drafts.create","tags":["Projects"],"summary":"Create a draft project","description":"Creates a draft project for a customer (`customerId`) or from a lead (`leadId`), as New project does in the app: the project starts in Draft with its first estimate revision and one unnamed phase. Add phases with `POST /v1/projects/{id}/estimate/phases` and lines with `POST /v1/projects/{id}/estimate/lines`; the answer is the empty estimate with the project's `version`, which each change sends back as `expectedVersion`. Nothing is sent to the customer, and no API call sends, approves, signs or bills a project: a person does that in Shortcut at `appUrl`. The workspace needs a default sales-tax rate in Settings > Projects. With `leadId`, the lead becomes a prospect linked to its customer account, as in the app, and workspace automations on that change may react if the token has `automations:trigger`. Send an `Idempotency-Key` to retry safely.\n\nReturns [the project estimate object](https://docs.shortcutco.com/developers/reference/objects/project-estimate).\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`project_estimate_edit_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#project_estimate_edit_not_allowed), [`projects_read_only`](https://docs.shortcutco.com/developers/concepts/errors#projects_read_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict), [`version_conflict`](https://docs.shortcutco.com/developers/concepts/errors#version_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","format":"uuid","description":"The customer the project is for. Send this or `leadId`, not both."},"leadId":{"type":"string","format":"uuid","description":"A lead to start the project from, instead of `customerId`. The lead must already have a customer account, as in the app; if its email belongs to an existing customer the project links to them, which needs `customers:write`."},"name":{"type":"string","minLength":1,"maxLength":120,"description":"The project's name, such as `Back patio and seat wall`."},"reference":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"description":"Your own reference, such as a bid or solicitation number."},"customerPoNumber":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"description":"The customer's purchase-order number."},"propertyId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"One of the customer's properties, where the work happens."}},"required":["name"],"additionalProperties":false,"description":"A new draft project."}}}},"responses":{"201":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectEstimate"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a project

> One project with its stage, customer, reference, and hold.\
> \
> Returns \[the project object]\(<https://docs.shortcutco.com/developers/reference/objects/project>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The project's id."},"object":{"type":"string","const":"project","description":"Always `project`."},"name":{"type":"string","description":"Its name."},"reference":{"type":["string","null"],"description":"The workspace's reference for it."},"customerPoNumber":{"type":["string","null"],"description":"The customer's purchase order number."},"stage":{"type":"string","description":"Where it stands, e.g. `draft`, `estimating`, `in_progress`, `complete`."},"customerId":{"type":"string","format":"uuid","description":"The customer it is for."},"customerName":{"type":"string","description":"The customer's name."},"onHold":{"type":"boolean","description":"Whether it is on hold."},"holdResumeDate":{"type":["string","null"],"description":"When a hold ends, `YYYY-MM-DD`."},"createdAt":{"type":"string","format":"date-time","description":"When it was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","name","reference","customerPoNumber","stage","customerId","customerName","onHold","holdResumeDate","createdAt","updatedAt"],"additionalProperties":false,"description":"A project: one-off construction or installation work with phases and change orders."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects/{id}":{"get":{"operationId":"projects.get","tags":["Projects"],"summary":"Get a project","description":"One project with its stage, customer, reference, and hold.\n\nReturns [the project object](https://docs.shortcutco.com/developers/reference/objects/project).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read a project's billing and deposit

> A project's payment schedule and what is left to bill: the signed contract, the deposit's state, each payment milestone (share, amount, trigger, status, why it is held), milestones reached and not invoiced, and T\&M and change-order work done and not billed. A project billed by progress (\`billingBasis: progress\`) also has its billing days and, per phase, the contract value, declared and billed percent, billed amount and what would bill now, plus the latest billing-day runs. With \`invoices:read\` and the person's invoice access it adds what was invoiced, collected and is owed, each milestone's invoice, and the progress figures read from invoices (billed and remaining, each phase's billed percent and amounts, what would bill now, a run's invoice); without, those are left out (\`invoicesWithheld\`). No cost or margin. Company admins with estimate access.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/{id}/billing":{"get":{"operationId":"projects.billing.get","tags":["Projects"],"summary":"Read a project's billing and deposit","description":"A project's payment schedule and what is left to bill: the signed contract, the deposit's state, each payment milestone (share, amount, trigger, status, why it is held), milestones reached and not invoiced, and T&M and change-order work done and not billed. A project billed by progress (`billingBasis: progress`) also has its billing days and, per phase, the contract value, declared and billed percent, billed amount and what would bill now, plus the latest billing-day runs. With `invoices:read` and the person's invoice access it adds what was invoiced, collected and is owed, each milestone's invoice, and the progress figures read from invoices (billed and remaining, each phase's billed percent and amounts, what would bill now, a run's invoice); without, those are left out (`invoicesWithheld`). No cost or margin. Company admins with estimate access.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reference":{"type":["string","null"]},"stage":{"type":"string","description":"draft, sent, approved, in_progress, ready_to_close, closed, lost, cancelled."},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"onHold":{"type":"boolean"},"holdReason":{"type":["string","null"]},"holdResumeDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"billingBasis":{"type":"string","enum":["milestones","progress"],"description":"How the fixed contract is billed: milestone payments, or progress (percent complete per phase on billing days)."},"billingDays":{"anyOf":[{"type":"object","properties":{"days":{"type":"array","items":{"type":"integer","minimum":1,"maximum":31},"description":"Days of the month progress is billed on; a day the month does not have falls on its last day."},"source":{"type":"string","enum":["project","company","none"],"description":"project: the project's own days; company: it follows the company's days; none: no billing days are set."},"next":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"The next billing date after today, in the company's timezone; null without days."}},"required":["days","source","next"],"additionalProperties":false},{"type":"null"}],"description":"Progress billing days; null on a project billed by milestones."},"progress":{"anyOf":[{"type":"object","properties":{"pool":{"type":"object","properties":{"sharePct":{"type":["number","null"],"description":"The progress share's percent of the fixed contract."},"amount":{"type":"number","description":"The progress share, before tax."},"billedPreTax":{"type":"number","description":"On progress invoices so far, sent or draft. Left out without invoice access."},"remainingPreTax":{"type":"number","description":"Not on any progress invoice yet. Left out without invoice access."}},"required":["sharePct","amount"],"additionalProperties":false},"phases":{"type":"array","items":{"type":"object","properties":{"phaseId":{"type":"string","format":"uuid"},"name":{"type":"string"},"contractValue":{"type":"number","description":"The phase's signed price after discount, before tax."},"declaredPct":{"type":"number","description":"Percent complete the crew or office last declared."},"billedPct":{"type":"number","description":"Percent already on progress invoices (sent or draft). Left out without invoice access."},"billedPreTax":{"type":"number","description":"The phase's progress billed so far (sent or draft), before tax. Left out without invoice access."},"toBillPreTax":{"type":"number","description":"What billing progress now would add for this phase, before tax: a reviewed phase counts as 100 %, a lowered percent bills nothing. Left out without invoice access."}},"required":["phaseId","name","contractValue","declaredPct"],"additionalProperties":false}},"recentRuns":{"type":"array","items":{"type":"object","properties":{"billingDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"outcome":{"type":"string","enum":["draft_created","nothing_to_bill","open_draft","blocked"]},"reason":{"type":["string","null"],"description":"A blocked run's reason code."},"invoiceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The draft the run made or found. Left out without invoice access."},"createdAt":{"type":"string","format":"date-time"}},"required":["billingDate","outcome","reason","createdAt"],"additionalProperties":false},"description":"The latest billing-day runs, newest first (at most 6). A run only makes drafts; nothing is sent."}},"required":["pool","phases","recentRuns"],"additionalProperties":false},{"type":"null"}],"description":"Progress billing per phase; null on a project billed by milestones, before a signature, or when `progressUnavailable` says why it cannot be read."},"progressUnavailable":{"anyOf":[{"type":"object","properties":{"reason":{"type":"string"}},"required":["reason"],"additionalProperties":false},{"type":"null"}],"description":"Set when a progress project's figures cannot be read (reason `split_inconsistent`: the signed phases or the progress share do not add up); billing it is refused until the office fixes it."},"contract":{"anyOf":[{"type":"object","properties":{"fixedBase":{"type":"number"},"fixedTax":{"type":"number"},"signedChangeOrdersPreTax":{"type":"number"},"timeAndMaterialsEstimatePreTax":{"type":"number"}},"required":["fixedBase","fixedTax","signedChangeOrdersPreTax","timeAndMaterialsEstimatePreTax"],"additionalProperties":false},{"type":"null"}],"description":"What the customer signed; null before a signature."},"deposit":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","enum":["paid","invoiced","not_requested","not_required"]},"reason":{"type":["string","null"],"description":"Why none is required: not_offered, under_threshold, waived, dropped, zero."},"sharePct":{"type":["number","null"]},"amount":{"type":["number","null"],"description":"With tax. Left out without invoice access."},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"daysWaiting":{"anyOf":[{"type":"integer"},{"type":"null"}]},"paidAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["state","reason","sharePct"],"additionalProperties":false},{"type":"null"}]},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","description":"deposit, progress, balance, retainage, change_order. A progress milestone with trigger by_progress is the progress billing share."},"label":{"type":"string"},"sharePct":{"type":["number","null"]},"amount":{"type":["number","null"],"description":"Before tax."},"status":{"type":"string","description":"upcoming, triggered (reached, to bill), held, invoiced, paid, waived, dropped. Without invoice access a paid one reads invoiced."},"trigger":{"type":"string","description":"What releases it: on_approval, phase_reviewed, closeout, days_after_closeout, co_signed, or by_progress (the share billed by percent complete per phase on billing days, invoiced once the whole share is on sent invoices; see `progress`)."},"triggerPhaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"daysAfter":{"anyOf":[{"type":"integer"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"held":{"anyOf":[{"type":"object","properties":{"reason":{"type":"string","enum":["punch_list","office"]},"note":{"type":["string","null"]}},"required":["reason","note"],"additionalProperties":false},{"type":"null"}],"description":"Why a held milestone waits: an open punch list, or the office."},"invoice":{"anyOf":[{"type":"object","properties":{"invoiceId":{"type":"string","format":"uuid"},"invoiceNumber":{"anyOf":[{"type":"integer"},{"type":"null"}]},"status":{"type":"string"},"total":{"type":"number"}},"required":["invoiceId","invoiceNumber","status","total"],"additionalProperties":false},{"type":"null"}],"description":"The invoice it is on. Left out without invoice access."}},"required":["id","kind","label","sharePct","amount","status","trigger","triggerPhaseId","daysAfter","dueAt","held"],"additionalProperties":false}},"toBill":{"anyOf":[{"type":"object","properties":{"milestonesPreTax":{"type":"number","description":"Live milestones not yet on an invoice (upcoming, triggered or held). The progress billing share (trigger by_progress) is not counted here: what it has left is `progressPreTax`."},"triggeredNotInvoiced":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Milestones reached and not invoiced yet."},"timeAndMaterialsPreTax":{"type":"number","description":"T&M work done and not billed."},"changeOrdersPreTax":{"type":"number","description":"Signed change orders billed on the next invoice and not billed yet."},"progressPreTax":{"type":"number","description":"Progress billing: the progress share not yet on a sent invoice (an unsent progress draft still counts). 0 on a project billed by milestones. Left out without invoice access."},"rows":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["phase","change_order"]},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"preTax":{"type":"number"}},"required":["kind","id","name","preTax"],"additionalProperties":false}}},"required":["milestonesPreTax","triggeredNotInvoiced","timeAndMaterialsPreTax","changeOrdersPreTax","rows"],"additionalProperties":false},{"type":"null"}],"description":"Null before a signature, or when a progress project's figures cannot be read (`progressUnavailable`)."},"invoiced":{"anyOf":[{"type":"object","properties":{"billed":{"type":"number"},"collectedNet":{"type":"number"},"refundsPending":{"type":"number"},"owed":{"type":"number"},"draftInvoices":{"type":"integer"},"invoices":{"type":"array","items":{"type":"object","properties":{"invoiceId":{"type":"string","format":"uuid"},"invoiceNumber":{"type":"integer"},"kind":{"type":"string","description":"deposit, milestone, change_order, final, retainage, tm, settlement, reversal, progress_billing."},"status":{"type":"string"},"total":{"type":"number"},"collectedNet":{"type":"number"},"openDispute":{"type":"boolean"}},"required":["invoiceId","invoiceNumber","kind","status","total","collectedNet","openDispute"],"additionalProperties":false}}},"required":["billed","collectedNet","refundsPending","owed","draftInvoices","invoices"],"additionalProperties":false},{"type":"null"}],"description":"What was invoiced, collected and is owed. Needs `invoices:read`, and the person's invoice access."},"invoicesWithheld":{"type":"boolean","description":"True when this person or token may not see invoice figures, so `invoiced`, deposit amounts, milestone invoices and the progress figures read from invoices (billed, remaining, to bill, a run's invoice) are left out."}},"required":["projectId","name","reference","stage","customerId","customerName","onHold","holdReason","holdResumeDate","billingBasis","billingDays","progress","progressUnavailable","contract","deposit","milestones","toBill","invoicesWithheld"],"additionalProperties":false},"meta":{"type":"object","properties":{"omitted":{"type":"array","items":{"type":"object","properties":{"section":{"type":"string","description":"The section left out of `data`."},"requiredScope":{"type":"string","description":"The scope that would include it."}},"required":["section","requiredScope"],"additionalProperties":false},"description":"Sections omitted because the token lacks their scope."}},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List a project's change orders

> A project's change orders, oldest first, as the project page lists them: status, reason, the sell price the customer was sent (fixed work), when it was sent, viewed, signed or declined, schedule impact, work started before signing, and the crew's field request it prices. Empty before the customer signs the estimate. No cost or margin. Company admins with estimate access.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/{id}/change-orders":{"get":{"operationId":"projects.change_orders.list","tags":["Projects"],"summary":"List a project's change orders","description":"A project's change orders, oldest first, as the project page lists them: status, reason, the sell price the customer was sent (fixed work), when it was sent, viewed, signed or declined, schedule impact, work started before signing, and the crew's field request it prices. Empty before the customer signs the estimate. No cost or margin. Company admins with estimate access.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reference":{"type":["string","null"]},"stage":{"type":"string","description":"draft, sent, approved, in_progress, ready_to_close, closed, lost, cancelled."},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"onHold":{"type":"boolean"},"holdReason":{"type":["string","null"]},"holdResumeDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"allResolved":{"type":"boolean","description":"No change order is waiting on a price, a signature or a decision."},"changeOrders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string","description":"`CO-2`; `Field request` before a draft has a number."},"status":{"type":"string","description":"draft, sent, approved, declined, expired, voided, converted_tm, internal_rework."},"reason":{"type":"string"},"billingMode":{"type":"string","description":"fixed or tm."},"priced":{"type":"boolean","description":"A revision was sent to the customer: there is a price for them to sign."},"preTax":{"type":["number","null"],"description":"What it adds to the contract before tax (the customer's current revision); null before a send or on T&M work."},"total":{"type":["number","null"],"description":"With tax; null before a send or on T&M work, which bills from actuals."},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"validUntil":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"customerViews":{"type":"integer"},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"approvalSource":{"type":["string","null"],"description":"How the approval came in (the customer's link, or recorded by the office)."},"declinedReason":{"type":["string","null"]},"scheduleImpactDays":{"type":"integer"},"startedBeforeSigned":{"type":"boolean"},"hasHours":{"type":"boolean","description":"Labor or on-site time is already on its phases."},"resolved":{"type":"boolean","description":"Signed, declined, voided or dismissed: nothing is waiting on it."},"draftBeingRevised":{"type":"boolean"},"fieldRequest":{"anyOf":[{"type":"object","properties":{"requestedBy":{"type":"string"},"requestedAt":{"type":"string"},"phaseName":{"type":"string"},"note":{"type":"string"},"photoCount":{"type":"integer"}},"required":["requestedBy","requestedAt","phaseName","note","photoCount"],"additionalProperties":false},{"type":"null"}],"description":"The crew's change request this change order prices, when it came from one."},"phaseIds":{"type":"array","items":{"type":"string","format":"uuid"}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","label","status","reason","billingMode","priced","preTax","total","sentAt","validUntil","customerViews","approvedAt","approvalSource","declinedReason","scheduleImpactDays","startedBeforeSigned","hasHours","resolved","draftBeingRevised","fieldRequest","phaseIds","createdAt"],"additionalProperties":false}}},"required":["projectId","name","reference","stage","customerId","customerName","onHold","holdReason","holdResumeDate","allResolved","changeOrders"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read a sent change order's original quote

> The exact identified current sent change-order revision and live terms, calculated by the native office reader. A revise draft and its draft terms never substitute. Requires current office estimate access. Returns scope, prices and schedule-impact terms without costs, pay, margins, contact information, payment details or bearer links.\
> \
> Returns \[the project object]\(<https://docs.shortcutco.com/developers/reference/objects/project).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`not\_found\`]\(<https://docs.shortcutco.com/developers/concepts/errors#not\\_found>), \[\`project\_details\_incomplete\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_incomplete>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"ProjectDetails":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"project"},"customerId":{"type":"string","format":"uuid"},"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["project_estimate","change_order"]},"revisionNumber":{"type":"integer"},"status":{"type":"string"},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"message":{"type":["string","null"]},"includesTimeAndMaterials":{"type":"boolean","description":"True when the quote includes T&M work. The calculated quote total is not a final T&M bill."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"name":{"type":"string"},"description":{"type":["string","null"]},"kind":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":["string","null"]},"unitPrice":{"anyOf":[{"type":"number"},{"type":"null"}]},"price":{"type":"number"},"discountAllocated":{"type":"number"},"included":{"type":"boolean"},"selected":{"type":"boolean"},"isOptional":{"type":"boolean"},"isCredit":{"type":"boolean"},"taxable":{"type":"boolean"}},"required":["id","phaseId","name","description","kind","quantity","unit","unitPrice","price","discountAllocated","included","selected","isOptional","isCredit","taxable"],"additionalProperties":false},"maxItems":2048},"phases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"billingMode":{"type":"string","enum":["fixed","tm"]},"workType":{"type":"string"},"budgetMinutes":{"type":"number"},"tmEstimatedMinutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"tmRatePerHour":{"anyOf":[{"type":"number"},{"type":"null"}]},"priceTotal":{"type":"number"},"discountAllocated":{"type":"number"},"priceAfterDiscount":{"type":"number"},"taxablePriceTotal":{"type":"number"}},"required":["id","name","billingMode","workType","budgetMinutes","tmEstimatedMinutes","tmRatePerHour","priceTotal","discountAllocated","priceAfterDiscount","taxablePriceTotal"],"additionalProperties":false},"maxItems":2048},"totals":{"type":"object","properties":{"subtotal":{"type":"number"},"discountAmount":{"type":"number"},"preTaxTotal":{"type":"number"},"tax":{"type":"number"},"quotedTotal":{"type":"number"}},"required":["subtotal","discountAmount","preTaxTotal","tax","quotedTotal"],"additionalProperties":false}},"required":["id","kind","revisionNumber","status","sentAt","expiresAt","signedAt","createdAt","updatedAt","message","includesTimeAndMaterials","lines","phases","totals"],"additionalProperties":false},"changeOrder":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"anyOf":[{"type":"integer"},{"type":"null"}]},"status":{"type":"string"},"reason":{"type":"string"},"billingMode":{"type":"string","enum":["fixed","tm"]},"scheduleImpactDays":{"type":"integer"},"startedBeforeSigned":{"type":"boolean"},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedReason":{"type":["string","null"]}},"required":["id","number","status","reason","billingMode","scheduleImpactDays","startedBeforeSigned","approvedAt","declinedReason"],"additionalProperties":false},{"type":"null"}]},"work":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"proposalPhaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"changeOrderId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"name":{"type":"string"},"source":{"type":"string"},"status":{"type":"string"},"pending":{"type":"boolean"},"budgetMinutes":{"type":"number"},"scheduleMinutes":{"type":"number"},"firstDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"lastDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"hold":{"anyOf":[{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"note":{"type":["string","null"]},"reason":{"type":["string","null"]},"resumeDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]}},"required":["at","note","reason","resumeDate"],"additionalProperties":false},{"type":"null"}]},"teams":{"type":"array","items":{"type":"object","properties":{"teamId":{"type":"string","format":"uuid"},"teamName":{"type":"string"},"days":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"status":{"type":"string"},"plannedMinutes":{"type":"number"}},"required":["id","date","status","plannedMinutes"],"additionalProperties":false},"maxItems":2048}},"required":["teamId","teamName","days"],"additionalProperties":false},"maxItems":2048}},"required":["id","proposalPhaseId","changeOrderId","name","source","status","pending","budgetMinutes","scheduleMinutes","firstDay","lastDay","hold","teams"],"additionalProperties":false},"maxItems":2048},{"type":"null"}],"description":"Complete native scheduling phases and displayed days, or null when scheduling detail was not requested."}},"required":["id","object","customerId","quote","changeOrder","work"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects/{id}/change-orders/{changeOrderId}/details":{"get":{"operationId":"projects.change_orders.details.get","tags":["Projects"],"summary":"Read a sent change order's original quote","description":"The exact identified current sent change-order revision and live terms, calculated by the native office reader. A revise draft and its draft terms never substitute. Requires current office estimate access. Returns scope, prices and schedule-impact terms without costs, pay, margins, contact information, payment details or bearer links.\n\nReturns [the project object](https://docs.shortcutco.com/developers/reference/objects/project).\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`not_found`](https://docs.shortcutco.com/developers/concepts/errors#not_found), [`project_details_incomplete`](https://docs.shortcutco.com/developers/concepts/errors#project_details_incomplete), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The parent Project ID.","schema":{"type":"string","format":"uuid"}},{"name":"changeOrderId","in":"path","required":true,"description":"The change-order ID.","schema":{"type":"string","format":"uuid"}},{"name":"proposalId","in":"query","required":true,"description":"The exact original sent change-order estimate ID from the audit.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectDetails"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read a project's closeout and warranty

> A project's closeout as the project page's Closeout section shows it: the step, what stops the closeout and Close (in words), retainage, the warranty's start and end, the lien waiver, a reopen for warranty work, and materials used less returns (quantities only). Billing blockers need \`invoices:read\` and the person's invoice access; otherwise they read as one line saying billing is not settled. Null before the customer signed. Company admins with estimate access.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/{id}/closeout":{"get":{"operationId":"projects.closeout.get","tags":["Projects"],"summary":"Read a project's closeout and warranty","description":"A project's closeout as the project page's Closeout section shows it: the step, what stops the closeout and Close (in words), retainage, the warranty's start and end, the lien waiver, a reopen for warranty work, and materials used less returns (quantities only). Billing blockers need `invoices:read` and the person's invoice access; otherwise they read as one line saying billing is not settled. Null before the customer signed. Company admins with estimate access.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reference":{"type":["string","null"]},"stage":{"type":"string","description":"draft, sent, approved, in_progress, ready_to_close, closed, lost, cancelled."},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"onHold":{"type":"boolean"},"holdReason":{"type":["string","null"]},"holdResumeDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"closeout":{"anyOf":[{"type":"object","properties":{"step":{"type":"string","description":"ready, punch_list_open, final_invoice_sent, awaiting_payment, retainage, close, closed, cancelled."},"readyToClose":{"type":"boolean"},"closedOutAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"closedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"gates":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"words":{"type":"string"}},"required":["code","words"],"additionalProperties":false},"description":"What stops the closeout: unreviewed phases, open punch lists, unbilled work, a change order awaiting signature."},"closeBlockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"words":{"type":"string"}},"required":["code","words"],"additionalProperties":false},"description":"What stops Close; without invoice access the billing blockers read as one line saying billing is not settled."},"retainage":{"anyOf":[{"type":"object","properties":{"status":{"type":"string"},"amount":{"type":["number","null"]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"daysAfter":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["status","amount","dueAt","daysAfter"],"additionalProperties":false},{"type":"null"}]},"warranty":{"type":"object","properties":{"startsAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"endsAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"months":{"type":"integer"},"lengthBasis":{"type":"string"}},"required":["startsAt","endsAt","months","lengthBasis"],"additionalProperties":false},"lienWaiver":{"anyOf":[{"type":"object","properties":{"received":{"type":"boolean"},"at":{"type":"string","format":"date-time"},"by":{"type":["string","null"]},"note":{"type":["string","null"]}},"required":["received","at","by","note"],"additionalProperties":false},{"type":"null"}]},"reopened":{"anyOf":[{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"phaseName":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["at","phaseName","reason"],"additionalProperties":false},{"type":"null"}]},"materials":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"unit":{"type":"string"},"used":{"type":"number"},"returned":{"type":"number"},"billed":{"type":"number"},"phaseId":{"type":"string","format":"uuid"}},"required":["name","unit","used","returned","billed","phaseId"],"additionalProperties":false},"description":"Materials the crews recorded, less returns; quantities only."}},"required":["step","readyToClose","closedOutAt","closedAt","gates","closeBlockers","retainage","warranty","lienWaiver","reopened","materials"],"additionalProperties":false},{"type":"null"}],"description":"Null before the customer signed."}},"required":["projectId","name","reference","stage","customerId","customerName","onHold","holdReason","holdResumeDate","closeout"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List a project's work days

> A project's work days, oldest first, at most 120: phase, crew and lead, the day's kind (work, a punch-list return day, rework) and status, hold, planned and finalized minutes, the office's note for the crew, the percent built the crew declared that day with their note, what the crew asked the office, and the ids of photos taken from the day's card. Released days are left out. Hours only, no money. Optional window (from, to). Company admins with estimate access, as the project page.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/{id}/days":{"get":{"operationId":"projects.days.list","tags":["Projects"],"summary":"List a project's work days","description":"A project's work days, oldest first, at most 120: phase, crew and lead, the day's kind (work, a punch-list return day, rework) and status, hold, planned and finalized minutes, the office's note for the crew, the percent built the crew declared that day with their note, what the crew asked the office, and the ids of photos taken from the day's card. Released days are left out. Hours only, no money. Optional window (from, to). Company admins with estimate access, as the project page.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Last day, YYYY-MM-DD.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reference":{"type":["string","null"]},"stage":{"type":"string"},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"from":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"to":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"days":{"type":"array","items":{"type":"object","properties":{"phaseDayId":{"type":"string","format":"uuid"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"phaseId":{"type":"string","format":"uuid"},"phaseName":{"type":"string"},"teamId":{"type":"string","format":"uuid"},"teamName":{"type":"string"},"lead":{"type":["string","null"]},"kind":{"type":"string","description":"work, punch_list (a return day for punch items), rework, filler."},"status":{"type":"string","description":"planned, active, done, held."},"holdReason":{"type":["string","null"]},"plannedMinutes":{"type":"number"},"workedMinutes":{"type":"number","description":"Finalized labor on the day; today's open clocks are not counted until they are."},"note":{"type":["string","null"],"description":"The office's note for the crew that day."},"noteBy":{"type":["string","null"]},"noteAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"progress":{"type":"array","items":{"type":"object","properties":{"declaredPct":{"type":"integer"},"declaredBy":{"type":["string","null"]},"declaredAt":{"type":"string","format":"date-time"},"note":{"type":["string","null"]}},"required":["declaredPct","declaredBy","declaredAt","note"],"additionalProperties":false},"description":"Percent built the crew or office declared on the day, with their note."},"requests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","description":"change_request, extra_materials, question."},"status":{"type":"string"},"note":{"type":"string"},"requestedBy":{"type":["string","null"]}},"required":["id","kind","status","note","requestedBy"],"additionalProperties":false},"description":"What the crew asked the office that day."},"photoIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Photos taken from the day's card, oldest first; list_project_photos describes them."}},"required":["phaseDayId","date","phaseId","phaseName","teamId","teamName","lead","kind","status","holdReason","plannedMinutes","workedMinutes","note","noteBy","noteAt","progress","requests","photoIds"],"additionalProperties":false},"description":"Oldest first; released days are left out."},"truncated":{"type":"boolean","description":"More than 120 days match; narrow the window."}},"required":["projectId","name","reference","stage","customerId","customerName","from","to","days","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read a Project's sent quote and scheduling detail

> The exact identified live sent or signed base quote, using native prices, with optional complete scheduling phases and days. Requires current office estimate access; scheduling also requires schedule.all and job/visit read scopes. A newer draft never substitutes for the requested quote. Costs, pay, margins, contact information and bearer links are omitted. This read creates no labor refresh or business changes.\
> \
> Returns \[the project object]\(<https://docs.shortcutco.com/developers/reference/objects/project).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`not\_found\`]\(<https://docs.shortcutco.com/developers/concepts/errors#not\\_found>), \[\`project\_details\_incomplete\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_incomplete>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"ProjectDetails":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"project"},"customerId":{"type":"string","format":"uuid"},"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["project_estimate","change_order"]},"revisionNumber":{"type":"integer"},"status":{"type":"string"},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"message":{"type":["string","null"]},"includesTimeAndMaterials":{"type":"boolean","description":"True when the quote includes T&M work. The calculated quote total is not a final T&M bill."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"name":{"type":"string"},"description":{"type":["string","null"]},"kind":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":["string","null"]},"unitPrice":{"anyOf":[{"type":"number"},{"type":"null"}]},"price":{"type":"number"},"discountAllocated":{"type":"number"},"included":{"type":"boolean"},"selected":{"type":"boolean"},"isOptional":{"type":"boolean"},"isCredit":{"type":"boolean"},"taxable":{"type":"boolean"}},"required":["id","phaseId","name","description","kind","quantity","unit","unitPrice","price","discountAllocated","included","selected","isOptional","isCredit","taxable"],"additionalProperties":false},"maxItems":2048},"phases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"billingMode":{"type":"string","enum":["fixed","tm"]},"workType":{"type":"string"},"budgetMinutes":{"type":"number"},"tmEstimatedMinutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"tmRatePerHour":{"anyOf":[{"type":"number"},{"type":"null"}]},"priceTotal":{"type":"number"},"discountAllocated":{"type":"number"},"priceAfterDiscount":{"type":"number"},"taxablePriceTotal":{"type":"number"}},"required":["id","name","billingMode","workType","budgetMinutes","tmEstimatedMinutes","tmRatePerHour","priceTotal","discountAllocated","priceAfterDiscount","taxablePriceTotal"],"additionalProperties":false},"maxItems":2048},"totals":{"type":"object","properties":{"subtotal":{"type":"number"},"discountAmount":{"type":"number"},"preTaxTotal":{"type":"number"},"tax":{"type":"number"},"quotedTotal":{"type":"number"}},"required":["subtotal","discountAmount","preTaxTotal","tax","quotedTotal"],"additionalProperties":false}},"required":["id","kind","revisionNumber","status","sentAt","expiresAt","signedAt","createdAt","updatedAt","message","includesTimeAndMaterials","lines","phases","totals"],"additionalProperties":false},"changeOrder":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"anyOf":[{"type":"integer"},{"type":"null"}]},"status":{"type":"string"},"reason":{"type":"string"},"billingMode":{"type":"string","enum":["fixed","tm"]},"scheduleImpactDays":{"type":"integer"},"startedBeforeSigned":{"type":"boolean"},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedReason":{"type":["string","null"]}},"required":["id","number","status","reason","billingMode","scheduleImpactDays","startedBeforeSigned","approvedAt","declinedReason"],"additionalProperties":false},{"type":"null"}]},"work":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"proposalPhaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"changeOrderId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"name":{"type":"string"},"source":{"type":"string"},"status":{"type":"string"},"pending":{"type":"boolean"},"budgetMinutes":{"type":"number"},"scheduleMinutes":{"type":"number"},"firstDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"lastDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"hold":{"anyOf":[{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"note":{"type":["string","null"]},"reason":{"type":["string","null"]},"resumeDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]}},"required":["at","note","reason","resumeDate"],"additionalProperties":false},{"type":"null"}]},"teams":{"type":"array","items":{"type":"object","properties":{"teamId":{"type":"string","format":"uuid"},"teamName":{"type":"string"},"days":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"status":{"type":"string"},"plannedMinutes":{"type":"number"}},"required":["id","date","status","plannedMinutes"],"additionalProperties":false},"maxItems":2048}},"required":["teamId","teamName","days"],"additionalProperties":false},"maxItems":2048}},"required":["id","proposalPhaseId","changeOrderId","name","source","status","pending","budgetMinutes","scheduleMinutes","firstDay","lastDay","hold","teams"],"additionalProperties":false},"maxItems":2048},{"type":"null"}],"description":"Complete native scheduling phases and displayed days, or null when scheduling detail was not requested."}},"required":["id","object","customerId","quote","changeOrder","work"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects/{id}/details":{"get":{"operationId":"projects.details.get","tags":["Projects"],"summary":"Read a Project's sent quote and scheduling detail","description":"The exact identified live sent or signed base quote, using native prices, with optional complete scheduling phases and days. Requires current office estimate access; scheduling also requires schedule.all and job/visit read scopes. A newer draft never substitutes for the requested quote. Costs, pay, margins, contact information and bearer links are omitted. This read creates no labor refresh or business changes.\n\nReturns [the project object](https://docs.shortcutco.com/developers/reference/objects/project).\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`not_found`](https://docs.shortcutco.com/developers/concepts/errors#not_found), [`project_details_incomplete`](https://docs.shortcutco.com/developers/concepts/errors#project_details_incomplete), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"proposalId","in":"query","required":true,"description":"The exact original live sent or signed base estimate ID, as supplied by the audit.","schema":{"type":"string","format":"uuid"}},{"name":"includeWork","in":"query","required":false,"description":"Include complete native scheduling phases and displayed days; requires schedule.all and jobs:read plus visits:read.","schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}],"default":false}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectDetails"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a project's estimate

> The project's current estimate as the estimate builder shows it: its phases (work type, fixed or time and materials, rate and estimated hours, planned team size), its lines (quantity, unit, unit price, price, tax, the price-book item it came from) and the totals (subtotal, discount, tax, total), with the project's \`version\` for the next change and \`appUrl\` to open it in Shortcut. \`editable\` is true while the estimate is a draft. Sell side only: cost, markup and margin are never returned. Company admins with estimate access.\
> \
> Returns \[the project estimate object]\(<https://docs.shortcutco.com/developers/reference/objects/project-estimate).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`project\_estimate\_edit\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_estimate\\_edit\\_not\\_allowed>), \[\`projects\_read\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#projects\\_read\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>), \[\`version\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#version\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"ProjectEstimate":{"type":"object","properties":{"object":{"type":"string","const":"project_estimate","description":"Always `project_estimate`."},"projectId":{"type":"string","format":"uuid","description":"The project's id."},"version":{"type":"integer","description":"The project's version. Send it as `expectedVersion` with the next change."},"name":{"type":"string","description":"The project's name."},"reference":{"type":["string","null"],"description":"The project's reference, such as a bid number."},"stage":{"type":"string","description":"The project's stage: `draft` until a person sends the estimate."},"customerId":{"type":"string","format":"uuid","description":"The customer the project is for."},"estimateId":{"type":"string","format":"uuid","description":"The estimate revision's id."},"revisionNumber":{"type":"integer","description":"Which revision of the estimate this is; 1 on a new project."},"status":{"type":"string","description":"The estimate revision's status. Only a `draft` can be changed."},"editable":{"type":"boolean","description":"Whether the estimate can be changed through the API: true while it is a draft."},"appUrl":{"type":"string","description":"Where a person opens this estimate in Shortcut to review and send it."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimatePhase"},"description":"The estimate's phases, in order."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimateLine"},"description":"The estimate's lines, in order."},"totals":{"type":"object","properties":{"subtotal":{"type":"number","description":"The sum of the lines' prices, in US dollars."},"discountAmount":{"type":"number","description":"The discount a person set in the app, in US dollars; 0 without one."},"preTaxTotal":{"type":"number","description":"The subtotal less the discount."},"taxRatePct":{"type":"number","description":"The project's sales-tax rate, in percent."},"tax":{"type":"number","description":"Sales tax on the taxable lines, in US dollars."},"total":{"type":"number","description":"What the customer would pay, in US dollars. A `tm` phase's part is an estimate, not a final bill."}},"required":["subtotal","discountAmount","preTaxTotal","taxRatePct","tax","total"],"additionalProperties":false,"description":"The estimate's totals, computed by the app."}},"required":["object","projectId","version","name","reference","stage","customerId","estimateId","revisionNumber","status","editable","appUrl","phases","lines","totals"],"additionalProperties":false,"description":"A project's current estimate with its phases, lines and totals. Sell side only: cost, markup and margin are never part of it."},"ProjectEstimatePhase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The phase's id."},"name":{"type":"string","description":"The phase's name."},"placeholder":{"type":"boolean","description":"True for the one unnamed phase a new project starts with; the app hides it until a second phase exists. The first phase you add takes its place while it is empty and untouched."},"workType":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"],"description":"The kind of work."},"billingMode":{"type":"string","enum":["fixed","tm"],"description":"`fixed`: sold at the sum of its lines. `tm`: time and materials, billed by the hour."},"tmRatePerHour":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's hourly rate in US dollars."},"tmEstimatedHours":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's estimated hours."},"tmLaborTaxable":{"type":["boolean","null"],"description":"Whether a `tm` phase's labor is taxed; null on a phase that was never `tm`."},"plannedTeamSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many people the phase is planned for."},"laborHours":{"type":"number","description":"Labor hours the phase's lines add up to."},"lineCount":{"type":"integer","description":"How many lines the phase has."},"priceTotal":{"type":"number","description":"The phase's price before discount and tax, in US dollars."}},"required":["id","name","placeholder","workType","billingMode","tmRatePerHour","tmEstimatedHours","tmLaborTaxable","plannedTeamSize","laborHours","lineCount","priceTotal"],"additionalProperties":false,"description":"One phase of a project's estimate."},"ProjectEstimateLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The line's id."},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The phase the line is in."},"name":{"type":"string","description":"The line's name."},"description":{"type":["string","null"],"description":"Shown under the line."},"kind":{"type":"string","enum":["material","labor","equipment","other"],"description":"`material`, `labor`, `equipment`, or `other`."},"quantity":{"type":"number","description":"Units sold. On a labor line with a production rate, the hours worked out from `measuredQuantity`."},"measuredQuantity":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"On a labor line with a production rate, the measured amount the hours come from (640 sq ft); null otherwise."},"unit":{"type":["string","null"],"description":"The unit the quantity counts, such as `sq ft` or `h`."},"unitPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"What one unit sells for, in US dollars."},"price":{"type":"number","description":"The line's price, in US dollars."},"taxable":{"type":"boolean","description":"Whether sales tax applies to the line."},"priceBookItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The price-book item the line was picked from; null on a typed-in line."}},"required":["id","phaseId","name","description","kind","quantity","measuredQuantity","unit","unitPrice","price","taxable","priceBookItemId"],"additionalProperties":false,"description":"One line of a project's estimate."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects/{id}/estimate":{"get":{"operationId":"projects.estimate.get","tags":["Projects"],"summary":"Get a project's estimate","description":"The project's current estimate as the estimate builder shows it: its phases (work type, fixed or time and materials, rate and estimated hours, planned team size), its lines (quantity, unit, unit price, price, tax, the price-book item it came from) and the totals (subtotal, discount, tax, total), with the project's `version` for the next change and `appUrl` to open it in Shortcut. `editable` is true while the estimate is a draft. Sell side only: cost, markup and margin are never returned. Company admins with estimate access.\n\nReturns [the project estimate object](https://docs.shortcutco.com/developers/reference/objects/project-estimate).\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`project_estimate_edit_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#project_estimate_edit_not_allowed), [`projects_read_only`](https://docs.shortcutco.com/developers/concepts/errors#projects_read_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict), [`version_conflict`](https://docs.shortcutco.com/developers/concepts/errors#version_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectEstimate"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Add lines to a draft estimate

> Adds up to 100 lines to a phase of a project's draft estimate, in the order sent, as the estimate builder does. A line is either a price-book item (\`priceBookItemId\` and \`quantity\`; its name, kind, unit, price, cost and tax setting come from the price book as they stand now, from \`GET /v1/projects/price-book\`) or typed in (\`name\`, \`kind\`, \`quantity\`, \`unit\`, \`unitPrice\`, and optionally \`unitCost\`, \`description\`, \`taxable\`). The app computes every price, the tax and the totals. \`unitCost\` is write-only: cost is never returned, and it is refused with \`403 margins\_not\_allowed\` unless the person the connection acts for can see margins. Without \`phaseId\` the lines go in the last phase. Only a draft estimate can be changed (\`409 state\_conflict\` otherwise). Send the project's \`version\` as \`expectedVersion\`; the answer is the estimate with the new version and totals. Nothing is sent to the customer. Send an \`Idempotency-Key\` to retry safely.\
> \
> Returns \[the project estimate object]\(<https://docs.shortcutco.com/developers/reference/objects/project-estimate).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>), \[\`margins\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#margins\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`project\_estimate\_edit\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_estimate\\_edit\\_not\\_allowed>), \[\`projects\_read\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#projects\\_read\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>), \[\`version\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#version\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"ProjectEstimateLinesAdded":{"type":"object","properties":{"object":{"type":"string","const":"project_estimate","description":"Always `project_estimate`."},"projectId":{"type":"string","format":"uuid","description":"The project's id."},"version":{"type":"integer","description":"The project's version. Send it as `expectedVersion` with the next change."},"name":{"type":"string","description":"The project's name."},"reference":{"type":["string","null"],"description":"The project's reference, such as a bid number."},"stage":{"type":"string","description":"The project's stage: `draft` until a person sends the estimate."},"customerId":{"type":"string","format":"uuid","description":"The customer the project is for."},"estimateId":{"type":"string","format":"uuid","description":"The estimate revision's id."},"revisionNumber":{"type":"integer","description":"Which revision of the estimate this is; 1 on a new project."},"status":{"type":"string","description":"The estimate revision's status. Only a `draft` can be changed."},"editable":{"type":"boolean","description":"Whether the estimate can be changed through the API: true while it is a draft."},"appUrl":{"type":"string","description":"Where a person opens this estimate in Shortcut to review and send it."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimatePhase"},"description":"The estimate's phases, in order."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimateLine"},"description":"The estimate's lines, in order."},"totals":{"type":"object","properties":{"subtotal":{"type":"number","description":"The sum of the lines' prices, in US dollars."},"discountAmount":{"type":"number","description":"The discount a person set in the app, in US dollars; 0 without one."},"preTaxTotal":{"type":"number","description":"The subtotal less the discount."},"taxRatePct":{"type":"number","description":"The project's sales-tax rate, in percent."},"tax":{"type":"number","description":"Sales tax on the taxable lines, in US dollars."},"total":{"type":"number","description":"What the customer would pay, in US dollars. A `tm` phase's part is an estimate, not a final bill."}},"required":["subtotal","discountAmount","preTaxTotal","taxRatePct","tax","total"],"additionalProperties":false,"description":"The estimate's totals, computed by the app."},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The phase the lines went in."},"lineIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The new lines, in the order sent."}},"required":["object","projectId","version","name","reference","stage","customerId","estimateId","revisionNumber","status","editable","appUrl","phases","lines","totals","phaseId","lineIds"],"additionalProperties":false,"description":"A project's estimate after lines were added."},"ProjectEstimatePhase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The phase's id."},"name":{"type":"string","description":"The phase's name."},"placeholder":{"type":"boolean","description":"True for the one unnamed phase a new project starts with; the app hides it until a second phase exists. The first phase you add takes its place while it is empty and untouched."},"workType":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"],"description":"The kind of work."},"billingMode":{"type":"string","enum":["fixed","tm"],"description":"`fixed`: sold at the sum of its lines. `tm`: time and materials, billed by the hour."},"tmRatePerHour":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's hourly rate in US dollars."},"tmEstimatedHours":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's estimated hours."},"tmLaborTaxable":{"type":["boolean","null"],"description":"Whether a `tm` phase's labor is taxed; null on a phase that was never `tm`."},"plannedTeamSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many people the phase is planned for."},"laborHours":{"type":"number","description":"Labor hours the phase's lines add up to."},"lineCount":{"type":"integer","description":"How many lines the phase has."},"priceTotal":{"type":"number","description":"The phase's price before discount and tax, in US dollars."}},"required":["id","name","placeholder","workType","billingMode","tmRatePerHour","tmEstimatedHours","tmLaborTaxable","plannedTeamSize","laborHours","lineCount","priceTotal"],"additionalProperties":false,"description":"One phase of a project's estimate."},"ProjectEstimateLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The line's id."},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The phase the line is in."},"name":{"type":"string","description":"The line's name."},"description":{"type":["string","null"],"description":"Shown under the line."},"kind":{"type":"string","enum":["material","labor","equipment","other"],"description":"`material`, `labor`, `equipment`, or `other`."},"quantity":{"type":"number","description":"Units sold. On a labor line with a production rate, the hours worked out from `measuredQuantity`."},"measuredQuantity":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"On a labor line with a production rate, the measured amount the hours come from (640 sq ft); null otherwise."},"unit":{"type":["string","null"],"description":"The unit the quantity counts, such as `sq ft` or `h`."},"unitPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"What one unit sells for, in US dollars."},"price":{"type":"number","description":"The line's price, in US dollars."},"taxable":{"type":"boolean","description":"Whether sales tax applies to the line."},"priceBookItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The price-book item the line was picked from; null on a typed-in line."}},"required":["id","phaseId","name","description","kind","quantity","measuredQuantity","unit","unitPrice","price","taxable","priceBookItemId"],"additionalProperties":false,"description":"One line of a project's estimate."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects/{id}/estimate/lines":{"post":{"operationId":"projects.estimate.lines.create","tags":["Projects"],"summary":"Add lines to a draft estimate","description":"Adds up to 100 lines to a phase of a project's draft estimate, in the order sent, as the estimate builder does. A line is either a price-book item (`priceBookItemId` and `quantity`; its name, kind, unit, price, cost and tax setting come from the price book as they stand now, from `GET /v1/projects/price-book`) or typed in (`name`, `kind`, `quantity`, `unit`, `unitPrice`, and optionally `unitCost`, `description`, `taxable`). The app computes every price, the tax and the totals. `unitCost` is write-only: cost is never returned, and it is refused with `403 margins_not_allowed` unless the person the connection acts for can see margins. Without `phaseId` the lines go in the last phase. Only a draft estimate can be changed (`409 state_conflict` otherwise). Send the project's `version` as `expectedVersion`; the answer is the estimate with the new version and totals. Nothing is sent to the customer. Send an `Idempotency-Key` to retry safely.\n\nReturns [the project estimate object](https://docs.shortcutco.com/developers/reference/objects/project-estimate).\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available), [`margins_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#margins_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`project_estimate_edit_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#project_estimate_edit_not_allowed), [`projects_read_only`](https://docs.shortcutco.com/developers/concepts/errors#projects_read_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict), [`version_conflict`](https://docs.shortcutco.com/developers/concepts/errors#version_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedVersion":{"type":"integer","minimum":1,"description":"The project's `version` as you last read it. A change made on an older version is refused with `version_conflict`; every answer carries the new one."},"phaseId":{"type":"string","format":"uuid","description":"The phase the lines go in. Defaults to the estimate's last phase."},"lines":{"type":"array","items":{"type":"object","properties":{"priceBookItemId":{"type":"string","format":"uuid","description":"A price-book item: its `itemId` from `GET /v1/projects/price-book`. The line takes the item's name, kind, unit, price, cost and tax setting, as picking it in the estimate builder does; send only `quantity` with it."},"name":{"type":"string","minLength":1,"maxLength":120,"description":"A typed-in line's name. Required without `priceBookItemId`."},"kind":{"type":"string","enum":["material","labor","equipment","other"],"description":"A typed-in line's kind. Required without `priceBookItemId`."},"quantity":{"type":"number","minimum":0,"maximum":1000000,"description":"How many units. Defaults to 1. For a price-book labor item with a production rate it is required: the measured amount in the item's unit (640 for 640 sq ft), which the hours are worked out from."},"unit":{"anyOf":[{"type":"string","maxLength":12},{"type":"null"}],"description":"A typed-in line's unit, such as `sq ft`, `ton` or `h`, up to 12 characters."},"unitPrice":{"type":"number","minimum":0,"maximum":1000000,"description":"What the customer pays per unit, in US dollars. Required on a typed-in line."},"unitCost":{"type":"number","minimum":0,"maximum":1000000,"description":"What one unit costs the company, in US dollars, on a typed-in line. Write-only: cost is never returned. Refused unless the person the connection acts for can see margins."},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Shown under a typed-in line."},"taxable":{"type":"boolean","description":"Whether sales tax applies to a typed-in line. Defaults to the workspace's setting for new items."}},"additionalProperties":false},"minItems":1,"maxItems":100,"description":"The lines, in the order they should appear. Each is a price-book item (`priceBookItemId` and `quantity`) or typed in (`name`, `kind`, `quantity`, `unit`, `unitPrice`, and optionally `unitCost`)."}},"required":["expectedVersion","lines"],"additionalProperties":false,"description":"Lines to add to a draft estimate."}}}},"responses":{"201":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectEstimateLinesAdded"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Remove a line from a draft estimate

> Removes one line from a project's draft estimate, as deleting its row does in the estimate builder. Only a draft estimate can be changed (\`409 state\_conflict\` otherwise). Send the project's \`version\` as \`expectedVersion\` in the query; the answer is the estimate with the new version and totals. Nothing is sent to the customer.\
> \
> Returns \[the project estimate object]\(<https://docs.shortcutco.com/developers/reference/objects/project-estimate).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`project\_estimate\_edit\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_estimate\\_edit\\_not\\_allowed>), \[\`projects\_read\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#projects\\_read\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>), \[\`version\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#version\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"ProjectEstimate":{"type":"object","properties":{"object":{"type":"string","const":"project_estimate","description":"Always `project_estimate`."},"projectId":{"type":"string","format":"uuid","description":"The project's id."},"version":{"type":"integer","description":"The project's version. Send it as `expectedVersion` with the next change."},"name":{"type":"string","description":"The project's name."},"reference":{"type":["string","null"],"description":"The project's reference, such as a bid number."},"stage":{"type":"string","description":"The project's stage: `draft` until a person sends the estimate."},"customerId":{"type":"string","format":"uuid","description":"The customer the project is for."},"estimateId":{"type":"string","format":"uuid","description":"The estimate revision's id."},"revisionNumber":{"type":"integer","description":"Which revision of the estimate this is; 1 on a new project."},"status":{"type":"string","description":"The estimate revision's status. Only a `draft` can be changed."},"editable":{"type":"boolean","description":"Whether the estimate can be changed through the API: true while it is a draft."},"appUrl":{"type":"string","description":"Where a person opens this estimate in Shortcut to review and send it."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimatePhase"},"description":"The estimate's phases, in order."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimateLine"},"description":"The estimate's lines, in order."},"totals":{"type":"object","properties":{"subtotal":{"type":"number","description":"The sum of the lines' prices, in US dollars."},"discountAmount":{"type":"number","description":"The discount a person set in the app, in US dollars; 0 without one."},"preTaxTotal":{"type":"number","description":"The subtotal less the discount."},"taxRatePct":{"type":"number","description":"The project's sales-tax rate, in percent."},"tax":{"type":"number","description":"Sales tax on the taxable lines, in US dollars."},"total":{"type":"number","description":"What the customer would pay, in US dollars. A `tm` phase's part is an estimate, not a final bill."}},"required":["subtotal","discountAmount","preTaxTotal","taxRatePct","tax","total"],"additionalProperties":false,"description":"The estimate's totals, computed by the app."}},"required":["object","projectId","version","name","reference","stage","customerId","estimateId","revisionNumber","status","editable","appUrl","phases","lines","totals"],"additionalProperties":false,"description":"A project's current estimate with its phases, lines and totals. Sell side only: cost, markup and margin are never part of it."},"ProjectEstimatePhase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The phase's id."},"name":{"type":"string","description":"The phase's name."},"placeholder":{"type":"boolean","description":"True for the one unnamed phase a new project starts with; the app hides it until a second phase exists. The first phase you add takes its place while it is empty and untouched."},"workType":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"],"description":"The kind of work."},"billingMode":{"type":"string","enum":["fixed","tm"],"description":"`fixed`: sold at the sum of its lines. `tm`: time and materials, billed by the hour."},"tmRatePerHour":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's hourly rate in US dollars."},"tmEstimatedHours":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's estimated hours."},"tmLaborTaxable":{"type":["boolean","null"],"description":"Whether a `tm` phase's labor is taxed; null on a phase that was never `tm`."},"plannedTeamSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many people the phase is planned for."},"laborHours":{"type":"number","description":"Labor hours the phase's lines add up to."},"lineCount":{"type":"integer","description":"How many lines the phase has."},"priceTotal":{"type":"number","description":"The phase's price before discount and tax, in US dollars."}},"required":["id","name","placeholder","workType","billingMode","tmRatePerHour","tmEstimatedHours","tmLaborTaxable","plannedTeamSize","laborHours","lineCount","priceTotal"],"additionalProperties":false,"description":"One phase of a project's estimate."},"ProjectEstimateLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The line's id."},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The phase the line is in."},"name":{"type":"string","description":"The line's name."},"description":{"type":["string","null"],"description":"Shown under the line."},"kind":{"type":"string","enum":["material","labor","equipment","other"],"description":"`material`, `labor`, `equipment`, or `other`."},"quantity":{"type":"number","description":"Units sold. On a labor line with a production rate, the hours worked out from `measuredQuantity`."},"measuredQuantity":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"On a labor line with a production rate, the measured amount the hours come from (640 sq ft); null otherwise."},"unit":{"type":["string","null"],"description":"The unit the quantity counts, such as `sq ft` or `h`."},"unitPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"What one unit sells for, in US dollars."},"price":{"type":"number","description":"The line's price, in US dollars."},"taxable":{"type":"boolean","description":"Whether sales tax applies to the line."},"priceBookItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The price-book item the line was picked from; null on a typed-in line."}},"required":["id","phaseId","name","description","kind","quantity","measuredQuantity","unit","unitPrice","price","taxable","priceBookItemId"],"additionalProperties":false,"description":"One line of a project's estimate."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects/{id}/estimate/lines/{lineId}":{"delete":{"operationId":"projects.estimate.lines.delete","tags":["Projects"],"summary":"Remove a line from a draft estimate","description":"Removes one line from a project's draft estimate, as deleting its row does in the estimate builder. Only a draft estimate can be changed (`409 state_conflict` otherwise). Send the project's `version` as `expectedVersion` in the query; the answer is the estimate with the new version and totals. Nothing is sent to the customer.\n\nReturns [the project estimate object](https://docs.shortcutco.com/developers/reference/objects/project-estimate).\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`project_estimate_edit_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#project_estimate_edit_not_allowed), [`projects_read_only`](https://docs.shortcutco.com/developers/concepts/errors#projects_read_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict), [`version_conflict`](https://docs.shortcutco.com/developers/concepts/errors#version_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The project's id.","schema":{"type":"string","format":"uuid"}},{"name":"lineId","in":"path","required":true,"description":"The line's id, from the estimate's `lines`.","schema":{"type":"string","format":"uuid"}},{"name":"expectedVersion","in":"query","required":true,"description":"The project's `version` as you last read it. A change made on an older version is refused with `version_conflict`.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectEstimate"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Update a line of a draft estimate

> Changes one line of a project's draft estimate, as editing its cells does in the estimate builder: name, description, quantity, unit, unit price, tax, or the phase it is in (\`phaseId\`). Send only what changes. On a price-book line \`unitPrice\` overrides the item's price and the kind stays the item's. \`unitCost\` is write-only and refused with \`403 margins\_not\_allowed\` unless the person the connection acts for can see margins. Only a draft estimate can be changed (\`409 state\_conflict\` otherwise). Send the project's \`version\` as \`expectedVersion\`; the answer is the estimate with the new version and totals. Nothing is sent to the customer.\
> \
> Returns \[the project estimate object]\(<https://docs.shortcutco.com/developers/reference/objects/project-estimate).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>), \[\`margins\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#margins\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`project\_estimate\_edit\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_estimate\\_edit\\_not\\_allowed>), \[\`projects\_read\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#projects\\_read\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>), \[\`version\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#version\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"ProjectEstimate":{"type":"object","properties":{"object":{"type":"string","const":"project_estimate","description":"Always `project_estimate`."},"projectId":{"type":"string","format":"uuid","description":"The project's id."},"version":{"type":"integer","description":"The project's version. Send it as `expectedVersion` with the next change."},"name":{"type":"string","description":"The project's name."},"reference":{"type":["string","null"],"description":"The project's reference, such as a bid number."},"stage":{"type":"string","description":"The project's stage: `draft` until a person sends the estimate."},"customerId":{"type":"string","format":"uuid","description":"The customer the project is for."},"estimateId":{"type":"string","format":"uuid","description":"The estimate revision's id."},"revisionNumber":{"type":"integer","description":"Which revision of the estimate this is; 1 on a new project."},"status":{"type":"string","description":"The estimate revision's status. Only a `draft` can be changed."},"editable":{"type":"boolean","description":"Whether the estimate can be changed through the API: true while it is a draft."},"appUrl":{"type":"string","description":"Where a person opens this estimate in Shortcut to review and send it."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimatePhase"},"description":"The estimate's phases, in order."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimateLine"},"description":"The estimate's lines, in order."},"totals":{"type":"object","properties":{"subtotal":{"type":"number","description":"The sum of the lines' prices, in US dollars."},"discountAmount":{"type":"number","description":"The discount a person set in the app, in US dollars; 0 without one."},"preTaxTotal":{"type":"number","description":"The subtotal less the discount."},"taxRatePct":{"type":"number","description":"The project's sales-tax rate, in percent."},"tax":{"type":"number","description":"Sales tax on the taxable lines, in US dollars."},"total":{"type":"number","description":"What the customer would pay, in US dollars. A `tm` phase's part is an estimate, not a final bill."}},"required":["subtotal","discountAmount","preTaxTotal","taxRatePct","tax","total"],"additionalProperties":false,"description":"The estimate's totals, computed by the app."}},"required":["object","projectId","version","name","reference","stage","customerId","estimateId","revisionNumber","status","editable","appUrl","phases","lines","totals"],"additionalProperties":false,"description":"A project's current estimate with its phases, lines and totals. Sell side only: cost, markup and margin are never part of it."},"ProjectEstimatePhase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The phase's id."},"name":{"type":"string","description":"The phase's name."},"placeholder":{"type":"boolean","description":"True for the one unnamed phase a new project starts with; the app hides it until a second phase exists. The first phase you add takes its place while it is empty and untouched."},"workType":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"],"description":"The kind of work."},"billingMode":{"type":"string","enum":["fixed","tm"],"description":"`fixed`: sold at the sum of its lines. `tm`: time and materials, billed by the hour."},"tmRatePerHour":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's hourly rate in US dollars."},"tmEstimatedHours":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's estimated hours."},"tmLaborTaxable":{"type":["boolean","null"],"description":"Whether a `tm` phase's labor is taxed; null on a phase that was never `tm`."},"plannedTeamSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many people the phase is planned for."},"laborHours":{"type":"number","description":"Labor hours the phase's lines add up to."},"lineCount":{"type":"integer","description":"How many lines the phase has."},"priceTotal":{"type":"number","description":"The phase's price before discount and tax, in US dollars."}},"required":["id","name","placeholder","workType","billingMode","tmRatePerHour","tmEstimatedHours","tmLaborTaxable","plannedTeamSize","laborHours","lineCount","priceTotal"],"additionalProperties":false,"description":"One phase of a project's estimate."},"ProjectEstimateLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The line's id."},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The phase the line is in."},"name":{"type":"string","description":"The line's name."},"description":{"type":["string","null"],"description":"Shown under the line."},"kind":{"type":"string","enum":["material","labor","equipment","other"],"description":"`material`, `labor`, `equipment`, or `other`."},"quantity":{"type":"number","description":"Units sold. On a labor line with a production rate, the hours worked out from `measuredQuantity`."},"measuredQuantity":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"On a labor line with a production rate, the measured amount the hours come from (640 sq ft); null otherwise."},"unit":{"type":["string","null"],"description":"The unit the quantity counts, such as `sq ft` or `h`."},"unitPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"What one unit sells for, in US dollars."},"price":{"type":"number","description":"The line's price, in US dollars."},"taxable":{"type":"boolean","description":"Whether sales tax applies to the line."},"priceBookItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The price-book item the line was picked from; null on a typed-in line."}},"required":["id","phaseId","name","description","kind","quantity","measuredQuantity","unit","unitPrice","price","taxable","priceBookItemId"],"additionalProperties":false,"description":"One line of a project's estimate."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects/{id}/estimate/lines/{lineId}":{"patch":{"operationId":"projects.estimate.lines.update","tags":["Projects"],"summary":"Update a line of a draft estimate","description":"Changes one line of a project's draft estimate, as editing its cells does in the estimate builder: name, description, quantity, unit, unit price, tax, or the phase it is in (`phaseId`). Send only what changes. On a price-book line `unitPrice` overrides the item's price and the kind stays the item's. `unitCost` is write-only and refused with `403 margins_not_allowed` unless the person the connection acts for can see margins. Only a draft estimate can be changed (`409 state_conflict` otherwise). Send the project's `version` as `expectedVersion`; the answer is the estimate with the new version and totals. Nothing is sent to the customer.\n\nReturns [the project estimate object](https://docs.shortcutco.com/developers/reference/objects/project-estimate).\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available), [`margins_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#margins_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`project_estimate_edit_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#project_estimate_edit_not_allowed), [`projects_read_only`](https://docs.shortcutco.com/developers/concepts/errors#projects_read_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict), [`version_conflict`](https://docs.shortcutco.com/developers/concepts/errors#version_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The project's id.","schema":{"type":"string","format":"uuid"}},{"name":"lineId","in":"path","required":true,"description":"The line's id, from the estimate's `lines`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedVersion":{"type":"integer","minimum":1,"description":"The project's `version` as you last read it. A change made on an older version is refused with `version_conflict`; every answer carries the new one."},"phaseId":{"type":"string","format":"uuid","description":"Moves the line to another phase of the estimate."},"name":{"type":"string","minLength":1,"maxLength":120,"description":"The line's name."},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Shown under the line; `null` clears it."},"kind":{"type":"string","enum":["material","labor","equipment","other"],"description":"A typed-in line's kind; a price-book line keeps its item's."},"quantity":{"type":"number","minimum":0,"maximum":1000000,"description":"How many units; on a labor line with a production rate, the measured amount the hours come from."},"unit":{"anyOf":[{"type":"string","maxLength":12},{"type":"null"}],"description":"The unit the quantity counts, up to 12 characters."},"unitPrice":{"type":"number","minimum":0,"maximum":1000000,"description":"What the customer pays per unit, in US dollars. On a price-book line this overrides the item's price."},"unitCost":{"anyOf":[{"type":"number","minimum":0,"maximum":1000000},{"type":"null"}],"description":"What one unit costs the company, in US dollars. Write-only, and refused unless the person the connection acts for can see margins."},"taxable":{"type":"boolean","description":"Whether sales tax applies to the line."}},"required":["expectedVersion"],"additionalProperties":false,"description":"Changes to one line of a draft estimate. Send only what changes."}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectEstimate"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Add a phase to a draft estimate

> Adds a phase to a project's draft estimate, as Add phase does in the estimate builder: its name, work type, and whether it is \`fixed\` (sold at the sum of its lines) or \`tm\` (time and materials, with an hourly rate and estimated hours). A new project starts with one unnamed phase the app hides; while that phase is empty and nobody has set anything on it, the first phase you add takes its place, so \`phaseId\` in the answer may be that phase's id. Only a draft estimate can be changed: an estimate that was sent, approved or signed answers \`409 state\_conflict\`. Send the project's \`version\` as \`expectedVersion\`; the answer is the estimate with the new version. Nothing is sent to the customer.\
> \
> Returns \[the project estimate object]\(<https://docs.shortcutco.com/developers/reference/objects/project-estimate).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`project\_estimate\_edit\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_estimate\\_edit\\_not\\_allowed>), \[\`projects\_read\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#projects\\_read\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>), \[\`version\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#version\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"ProjectEstimatePhaseAdded":{"type":"object","properties":{"object":{"type":"string","const":"project_estimate","description":"Always `project_estimate`."},"projectId":{"type":"string","format":"uuid","description":"The project's id."},"version":{"type":"integer","description":"The project's version. Send it as `expectedVersion` with the next change."},"name":{"type":"string","description":"The project's name."},"reference":{"type":["string","null"],"description":"The project's reference, such as a bid number."},"stage":{"type":"string","description":"The project's stage: `draft` until a person sends the estimate."},"customerId":{"type":"string","format":"uuid","description":"The customer the project is for."},"estimateId":{"type":"string","format":"uuid","description":"The estimate revision's id."},"revisionNumber":{"type":"integer","description":"Which revision of the estimate this is; 1 on a new project."},"status":{"type":"string","description":"The estimate revision's status. Only a `draft` can be changed."},"editable":{"type":"boolean","description":"Whether the estimate can be changed through the API: true while it is a draft."},"appUrl":{"type":"string","description":"Where a person opens this estimate in Shortcut to review and send it."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimatePhase"},"description":"The estimate's phases, in order."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimateLine"},"description":"The estimate's lines, in order."},"totals":{"type":"object","properties":{"subtotal":{"type":"number","description":"The sum of the lines' prices, in US dollars."},"discountAmount":{"type":"number","description":"The discount a person set in the app, in US dollars; 0 without one."},"preTaxTotal":{"type":"number","description":"The subtotal less the discount."},"taxRatePct":{"type":"number","description":"The project's sales-tax rate, in percent."},"tax":{"type":"number","description":"Sales tax on the taxable lines, in US dollars."},"total":{"type":"number","description":"What the customer would pay, in US dollars. A `tm` phase's part is an estimate, not a final bill."}},"required":["subtotal","discountAmount","preTaxTotal","taxRatePct","tax","total"],"additionalProperties":false,"description":"The estimate's totals, computed by the app."},"phaseId":{"type":"string","format":"uuid","description":"The phase that was added. It is the project's starting phase when that phase was still unnamed, empty and untouched."}},"required":["object","projectId","version","name","reference","stage","customerId","estimateId","revisionNumber","status","editable","appUrl","phases","lines","totals","phaseId"],"additionalProperties":false,"description":"A project's estimate after a phase was added."},"ProjectEstimatePhase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The phase's id."},"name":{"type":"string","description":"The phase's name."},"placeholder":{"type":"boolean","description":"True for the one unnamed phase a new project starts with; the app hides it until a second phase exists. The first phase you add takes its place while it is empty and untouched."},"workType":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"],"description":"The kind of work."},"billingMode":{"type":"string","enum":["fixed","tm"],"description":"`fixed`: sold at the sum of its lines. `tm`: time and materials, billed by the hour."},"tmRatePerHour":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's hourly rate in US dollars."},"tmEstimatedHours":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's estimated hours."},"tmLaborTaxable":{"type":["boolean","null"],"description":"Whether a `tm` phase's labor is taxed; null on a phase that was never `tm`."},"plannedTeamSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many people the phase is planned for."},"laborHours":{"type":"number","description":"Labor hours the phase's lines add up to."},"lineCount":{"type":"integer","description":"How many lines the phase has."},"priceTotal":{"type":"number","description":"The phase's price before discount and tax, in US dollars."}},"required":["id","name","placeholder","workType","billingMode","tmRatePerHour","tmEstimatedHours","tmLaborTaxable","plannedTeamSize","laborHours","lineCount","priceTotal"],"additionalProperties":false,"description":"One phase of a project's estimate."},"ProjectEstimateLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The line's id."},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The phase the line is in."},"name":{"type":"string","description":"The line's name."},"description":{"type":["string","null"],"description":"Shown under the line."},"kind":{"type":"string","enum":["material","labor","equipment","other"],"description":"`material`, `labor`, `equipment`, or `other`."},"quantity":{"type":"number","description":"Units sold. On a labor line with a production rate, the hours worked out from `measuredQuantity`."},"measuredQuantity":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"On a labor line with a production rate, the measured amount the hours come from (640 sq ft); null otherwise."},"unit":{"type":["string","null"],"description":"The unit the quantity counts, such as `sq ft` or `h`."},"unitPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"What one unit sells for, in US dollars."},"price":{"type":"number","description":"The line's price, in US dollars."},"taxable":{"type":"boolean","description":"Whether sales tax applies to the line."},"priceBookItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The price-book item the line was picked from; null on a typed-in line."}},"required":["id","phaseId","name","description","kind","quantity","measuredQuantity","unit","unitPrice","price","taxable","priceBookItemId"],"additionalProperties":false,"description":"One line of a project's estimate."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects/{id}/estimate/phases":{"post":{"operationId":"projects.estimate.phases.create","tags":["Projects"],"summary":"Add a phase to a draft estimate","description":"Adds a phase to a project's draft estimate, as Add phase does in the estimate builder: its name, work type, and whether it is `fixed` (sold at the sum of its lines) or `tm` (time and materials, with an hourly rate and estimated hours). A new project starts with one unnamed phase the app hides; while that phase is empty and nobody has set anything on it, the first phase you add takes its place, so `phaseId` in the answer may be that phase's id. Only a draft estimate can be changed: an estimate that was sent, approved or signed answers `409 state_conflict`. Send the project's `version` as `expectedVersion`; the answer is the estimate with the new version. Nothing is sent to the customer.\n\nReturns [the project estimate object](https://docs.shortcutco.com/developers/reference/objects/project-estimate).\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`project_estimate_edit_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#project_estimate_edit_not_allowed), [`projects_read_only`](https://docs.shortcutco.com/developers/concepts/errors#projects_read_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict), [`version_conflict`](https://docs.shortcutco.com/developers/concepts/errors#version_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedVersion":{"type":"integer","minimum":1,"description":"The project's `version` as you last read it. A change made on an older version is refused with `version_conflict`; every answer carries the new one."},"name":{"type":"string","minLength":1,"maxLength":120,"description":"The phase's name, such as `Demo and haul-off`."},"workType":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"],"description":"The kind of work. Defaults to `other`."},"billingMode":{"type":"string","enum":["fixed","tm"],"description":"`fixed` (the default): the phase sells at the sum of its lines. `tm`: time and materials, billed by the hour at `tmRatePerHour`."},"tmRatePerHour":{"anyOf":[{"type":"number","minimum":0,"maximum":1000000},{"type":"null"}],"description":"A `tm` phase's hourly rate in US dollars."},"tmEstimatedHours":{"anyOf":[{"type":"number","minimum":0,"maximum":10000},{"type":"null"}],"description":"A `tm` phase's estimated hours, to two decimals."},"tmLaborTaxable":{"type":["boolean","null"],"description":"Whether a `tm` phase's labor is taxed. Defaults to the workspace's setting."},"plannedTeamSize":{"anyOf":[{"type":"integer","minimum":1,"maximum":50},{"type":"null"}],"description":"How many people the phase is planned for."}},"required":["expectedVersion","name"],"additionalProperties":false,"description":"A new phase of a draft estimate."}}}},"responses":{"201":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectEstimatePhaseAdded"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Remove a phase from a draft estimate

> Removes a phase from a project's draft estimate, as Delete phase does in the estimate builder. A phase that still has lines needs \`moveLinesTo\` (another phase's id) or \`deleteLines=true\`; an estimate keeps at least one phase, and a phase that carries the estimate's discount stays until a person moves the discount. Only a draft estimate can be changed (\`409 state\_conflict\` otherwise). Send the project's \`version\` as \`expectedVersion\` in the query; the answer is the estimate with the new version. Nothing is sent to the customer.\
> \
> Returns \[the project estimate object]\(<https://docs.shortcutco.com/developers/reference/objects/project-estimate).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`project\_estimate\_edit\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_estimate\\_edit\\_not\\_allowed>), \[\`projects\_read\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#projects\\_read\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>), \[\`version\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#version\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"ProjectEstimate":{"type":"object","properties":{"object":{"type":"string","const":"project_estimate","description":"Always `project_estimate`."},"projectId":{"type":"string","format":"uuid","description":"The project's id."},"version":{"type":"integer","description":"The project's version. Send it as `expectedVersion` with the next change."},"name":{"type":"string","description":"The project's name."},"reference":{"type":["string","null"],"description":"The project's reference, such as a bid number."},"stage":{"type":"string","description":"The project's stage: `draft` until a person sends the estimate."},"customerId":{"type":"string","format":"uuid","description":"The customer the project is for."},"estimateId":{"type":"string","format":"uuid","description":"The estimate revision's id."},"revisionNumber":{"type":"integer","description":"Which revision of the estimate this is; 1 on a new project."},"status":{"type":"string","description":"The estimate revision's status. Only a `draft` can be changed."},"editable":{"type":"boolean","description":"Whether the estimate can be changed through the API: true while it is a draft."},"appUrl":{"type":"string","description":"Where a person opens this estimate in Shortcut to review and send it."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimatePhase"},"description":"The estimate's phases, in order."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimateLine"},"description":"The estimate's lines, in order."},"totals":{"type":"object","properties":{"subtotal":{"type":"number","description":"The sum of the lines' prices, in US dollars."},"discountAmount":{"type":"number","description":"The discount a person set in the app, in US dollars; 0 without one."},"preTaxTotal":{"type":"number","description":"The subtotal less the discount."},"taxRatePct":{"type":"number","description":"The project's sales-tax rate, in percent."},"tax":{"type":"number","description":"Sales tax on the taxable lines, in US dollars."},"total":{"type":"number","description":"What the customer would pay, in US dollars. A `tm` phase's part is an estimate, not a final bill."}},"required":["subtotal","discountAmount","preTaxTotal","taxRatePct","tax","total"],"additionalProperties":false,"description":"The estimate's totals, computed by the app."}},"required":["object","projectId","version","name","reference","stage","customerId","estimateId","revisionNumber","status","editable","appUrl","phases","lines","totals"],"additionalProperties":false,"description":"A project's current estimate with its phases, lines and totals. Sell side only: cost, markup and margin are never part of it."},"ProjectEstimatePhase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The phase's id."},"name":{"type":"string","description":"The phase's name."},"placeholder":{"type":"boolean","description":"True for the one unnamed phase a new project starts with; the app hides it until a second phase exists. The first phase you add takes its place while it is empty and untouched."},"workType":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"],"description":"The kind of work."},"billingMode":{"type":"string","enum":["fixed","tm"],"description":"`fixed`: sold at the sum of its lines. `tm`: time and materials, billed by the hour."},"tmRatePerHour":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's hourly rate in US dollars."},"tmEstimatedHours":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's estimated hours."},"tmLaborTaxable":{"type":["boolean","null"],"description":"Whether a `tm` phase's labor is taxed; null on a phase that was never `tm`."},"plannedTeamSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many people the phase is planned for."},"laborHours":{"type":"number","description":"Labor hours the phase's lines add up to."},"lineCount":{"type":"integer","description":"How many lines the phase has."},"priceTotal":{"type":"number","description":"The phase's price before discount and tax, in US dollars."}},"required":["id","name","placeholder","workType","billingMode","tmRatePerHour","tmEstimatedHours","tmLaborTaxable","plannedTeamSize","laborHours","lineCount","priceTotal"],"additionalProperties":false,"description":"One phase of a project's estimate."},"ProjectEstimateLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The line's id."},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The phase the line is in."},"name":{"type":"string","description":"The line's name."},"description":{"type":["string","null"],"description":"Shown under the line."},"kind":{"type":"string","enum":["material","labor","equipment","other"],"description":"`material`, `labor`, `equipment`, or `other`."},"quantity":{"type":"number","description":"Units sold. On a labor line with a production rate, the hours worked out from `measuredQuantity`."},"measuredQuantity":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"On a labor line with a production rate, the measured amount the hours come from (640 sq ft); null otherwise."},"unit":{"type":["string","null"],"description":"The unit the quantity counts, such as `sq ft` or `h`."},"unitPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"What one unit sells for, in US dollars."},"price":{"type":"number","description":"The line's price, in US dollars."},"taxable":{"type":"boolean","description":"Whether sales tax applies to the line."},"priceBookItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The price-book item the line was picked from; null on a typed-in line."}},"required":["id","phaseId","name","description","kind","quantity","measuredQuantity","unit","unitPrice","price","taxable","priceBookItemId"],"additionalProperties":false,"description":"One line of a project's estimate."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects/{id}/estimate/phases/{phaseId}":{"delete":{"operationId":"projects.estimate.phases.delete","tags":["Projects"],"summary":"Remove a phase from a draft estimate","description":"Removes a phase from a project's draft estimate, as Delete phase does in the estimate builder. A phase that still has lines needs `moveLinesTo` (another phase's id) or `deleteLines=true`; an estimate keeps at least one phase, and a phase that carries the estimate's discount stays until a person moves the discount. Only a draft estimate can be changed (`409 state_conflict` otherwise). Send the project's `version` as `expectedVersion` in the query; the answer is the estimate with the new version. Nothing is sent to the customer.\n\nReturns [the project estimate object](https://docs.shortcutco.com/developers/reference/objects/project-estimate).\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`project_estimate_edit_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#project_estimate_edit_not_allowed), [`projects_read_only`](https://docs.shortcutco.com/developers/concepts/errors#projects_read_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict), [`version_conflict`](https://docs.shortcutco.com/developers/concepts/errors#version_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The project's id.","schema":{"type":"string","format":"uuid"}},{"name":"phaseId","in":"path","required":true,"description":"The phase's id, from the estimate's `phases`.","schema":{"type":"string","format":"uuid"}},{"name":"expectedVersion","in":"query","required":true,"description":"The project's `version` as you last read it. A change made on an older version is refused with `version_conflict`.","schema":{"type":"integer","minimum":1}},{"name":"moveLinesTo","in":"query","required":false,"description":"Another phase of the estimate to move this phase's lines to.","schema":{"type":"string","format":"uuid"}},{"name":"deleteLines","in":"query","required":false,"description":"`true` deletes the phase's lines with it. A phase that still has lines needs this or `moveLinesTo`.","schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectEstimate"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Update a phase of a draft estimate

> Changes a phase of a project's draft estimate, as the phase's settings do in the estimate builder: name, work type, \`fixed\` or \`tm\` billing, a \`tm\` phase's hourly rate, estimated hours and labor tax, and the planned team size. Send only what changes. Setting a phase back to \`fixed\` clears its rate and estimated hours. Only a draft estimate can be changed (\`409 state\_conflict\` otherwise). Send the project's \`version\` as \`expectedVersion\`; the answer is the estimate with the new version. Nothing is sent to the customer.\
> \
> Returns \[the project estimate object]\(<https://docs.shortcutco.com/developers/reference/objects/project-estimate).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`project\_estimate\_edit\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_estimate\\_edit\\_not\\_allowed>), \[\`projects\_read\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#projects\\_read\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>), \[\`version\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#version\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"ProjectEstimate":{"type":"object","properties":{"object":{"type":"string","const":"project_estimate","description":"Always `project_estimate`."},"projectId":{"type":"string","format":"uuid","description":"The project's id."},"version":{"type":"integer","description":"The project's version. Send it as `expectedVersion` with the next change."},"name":{"type":"string","description":"The project's name."},"reference":{"type":["string","null"],"description":"The project's reference, such as a bid number."},"stage":{"type":"string","description":"The project's stage: `draft` until a person sends the estimate."},"customerId":{"type":"string","format":"uuid","description":"The customer the project is for."},"estimateId":{"type":"string","format":"uuid","description":"The estimate revision's id."},"revisionNumber":{"type":"integer","description":"Which revision of the estimate this is; 1 on a new project."},"status":{"type":"string","description":"The estimate revision's status. Only a `draft` can be changed."},"editable":{"type":"boolean","description":"Whether the estimate can be changed through the API: true while it is a draft."},"appUrl":{"type":"string","description":"Where a person opens this estimate in Shortcut to review and send it."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimatePhase"},"description":"The estimate's phases, in order."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ProjectEstimateLine"},"description":"The estimate's lines, in order."},"totals":{"type":"object","properties":{"subtotal":{"type":"number","description":"The sum of the lines' prices, in US dollars."},"discountAmount":{"type":"number","description":"The discount a person set in the app, in US dollars; 0 without one."},"preTaxTotal":{"type":"number","description":"The subtotal less the discount."},"taxRatePct":{"type":"number","description":"The project's sales-tax rate, in percent."},"tax":{"type":"number","description":"Sales tax on the taxable lines, in US dollars."},"total":{"type":"number","description":"What the customer would pay, in US dollars. A `tm` phase's part is an estimate, not a final bill."}},"required":["subtotal","discountAmount","preTaxTotal","taxRatePct","tax","total"],"additionalProperties":false,"description":"The estimate's totals, computed by the app."}},"required":["object","projectId","version","name","reference","stage","customerId","estimateId","revisionNumber","status","editable","appUrl","phases","lines","totals"],"additionalProperties":false,"description":"A project's current estimate with its phases, lines and totals. Sell side only: cost, markup and margin are never part of it."},"ProjectEstimatePhase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The phase's id."},"name":{"type":"string","description":"The phase's name."},"placeholder":{"type":"boolean","description":"True for the one unnamed phase a new project starts with; the app hides it until a second phase exists. The first phase you add takes its place while it is empty and untouched."},"workType":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"],"description":"The kind of work."},"billingMode":{"type":"string","enum":["fixed","tm"],"description":"`fixed`: sold at the sum of its lines. `tm`: time and materials, billed by the hour."},"tmRatePerHour":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's hourly rate in US dollars."},"tmEstimatedHours":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A `tm` phase's estimated hours."},"tmLaborTaxable":{"type":["boolean","null"],"description":"Whether a `tm` phase's labor is taxed; null on a phase that was never `tm`."},"plannedTeamSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many people the phase is planned for."},"laborHours":{"type":"number","description":"Labor hours the phase's lines add up to."},"lineCount":{"type":"integer","description":"How many lines the phase has."},"priceTotal":{"type":"number","description":"The phase's price before discount and tax, in US dollars."}},"required":["id","name","placeholder","workType","billingMode","tmRatePerHour","tmEstimatedHours","tmLaborTaxable","plannedTeamSize","laborHours","lineCount","priceTotal"],"additionalProperties":false,"description":"One phase of a project's estimate."},"ProjectEstimateLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The line's id."},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The phase the line is in."},"name":{"type":"string","description":"The line's name."},"description":{"type":["string","null"],"description":"Shown under the line."},"kind":{"type":"string","enum":["material","labor","equipment","other"],"description":"`material`, `labor`, `equipment`, or `other`."},"quantity":{"type":"number","description":"Units sold. On a labor line with a production rate, the hours worked out from `measuredQuantity`."},"measuredQuantity":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"On a labor line with a production rate, the measured amount the hours come from (640 sq ft); null otherwise."},"unit":{"type":["string","null"],"description":"The unit the quantity counts, such as `sq ft` or `h`."},"unitPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"What one unit sells for, in US dollars."},"price":{"type":"number","description":"The line's price, in US dollars."},"taxable":{"type":"boolean","description":"Whether sales tax applies to the line."},"priceBookItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The price-book item the line was picked from; null on a typed-in line."}},"required":["id","phaseId","name","description","kind","quantity","measuredQuantity","unit","unitPrice","price","taxable","priceBookItemId"],"additionalProperties":false,"description":"One line of a project's estimate."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/projects/{id}/estimate/phases/{phaseId}":{"patch":{"operationId":"projects.estimate.phases.update","tags":["Projects"],"summary":"Update a phase of a draft estimate","description":"Changes a phase of a project's draft estimate, as the phase's settings do in the estimate builder: name, work type, `fixed` or `tm` billing, a `tm` phase's hourly rate, estimated hours and labor tax, and the planned team size. Send only what changes. Setting a phase back to `fixed` clears its rate and estimated hours. Only a draft estimate can be changed (`409 state_conflict` otherwise). Send the project's `version` as `expectedVersion`; the answer is the estimate with the new version. Nothing is sent to the customer.\n\nReturns [the project estimate object](https://docs.shortcutco.com/developers/reference/objects/project-estimate).\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`project_estimate_edit_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#project_estimate_edit_not_allowed), [`projects_read_only`](https://docs.shortcutco.com/developers/concepts/errors#projects_read_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict), [`version_conflict`](https://docs.shortcutco.com/developers/concepts/errors#version_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The project's id.","schema":{"type":"string","format":"uuid"}},{"name":"phaseId","in":"path","required":true,"description":"The phase's id, from the estimate's `phases`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedVersion":{"type":"integer","minimum":1,"description":"The project's `version` as you last read it. A change made on an older version is refused with `version_conflict`; every answer carries the new one."},"name":{"type":"string","minLength":1,"maxLength":120,"description":"The phase's name, such as `Demo and haul-off`."},"workType":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"],"description":"The kind of work. Defaults to `other`."},"billingMode":{"type":"string","enum":["fixed","tm"],"description":"`fixed` (the default): the phase sells at the sum of its lines. `tm`: time and materials, billed by the hour at `tmRatePerHour`."},"tmRatePerHour":{"anyOf":[{"type":"number","minimum":0,"maximum":1000000},{"type":"null"}],"description":"A `tm` phase's hourly rate in US dollars."},"tmEstimatedHours":{"anyOf":[{"type":"number","minimum":0,"maximum":10000},{"type":"null"}],"description":"A `tm` phase's estimated hours, to two decimals."},"tmLaborTaxable":{"type":["boolean","null"],"description":"Whether a `tm` phase's labor is taxed. Defaults to the workspace's setting."},"plannedTeamSize":{"anyOf":[{"type":"integer","minimum":1,"maximum":50},{"type":"null"}],"description":"How many people the phase is planned for."}},"required":["expectedVersion"],"additionalProperties":false,"description":"Changes to a phase of a draft estimate. Send only what changes."}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectEstimate"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List a project's photos

> A project's photos as facts, newest first, at most 200: caption, phase, the work day and crew it was taken on, the punch item it shows (before or after), the crew request it came with, who took it and when, whether the customer sees it, and whether the office still has to accept a field photo with a doubtful time. No image bytes; open one with \`view\_attachment\`. Company admins with estimate access, as the project page.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/{id}/photos":{"get":{"operationId":"projects.photos.list","tags":["Projects"],"summary":"List a project's photos","description":"A project's photos as facts, newest first, at most 200: caption, phase, the work day and crew it was taken on, the punch item it shows (before or after), the crew request it came with, who took it and when, whether the customer sees it, and whether the office still has to accept a field photo with a doubtful time. No image bytes; open one with `view_attachment`. Company admins with estimate access, as the project page.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"phaseId","in":"query","required":false,"description":"Only this phase's photos.","schema":{"type":"string","format":"uuid"}},{"name":"date","in":"query","required":false,"description":"Only photos taken from a crew's card on this work day, YYYY-MM-DD.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reference":{"type":["string","null"]},"stage":{"type":"string"},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"photos":{"type":"array","items":{"type":"object","properties":{"attachmentId":{"type":"string","format":"uuid","description":"Open it with view_attachment (source `project`)."},"contentType":{"type":"string"},"caption":{"type":["string","null"],"description":"What the person who took it wrote."},"phaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"phaseName":{"type":["string","null"]},"day":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"The work day it was taken on, when it was taken from a crew's day card."},"teamName":{"type":["string","null"]},"punchItem":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"side":{"type":"string","enum":["before","after","attached"]}},"required":["id","title","side"],"additionalProperties":false},{"type":"null"}]},"fieldRequestId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The crew's change request or question it was sent with."},"takenBy":{"type":["string","null"]},"capturedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"The phone's time when it was taken (offline uploads)."},"receivedAt":{"type":"string","format":"date-time"},"sharedWithCustomer":{"type":"boolean","description":"Shown on the customer's estimate and change-order pages."},"awaitingAcceptance":{"type":"boolean","description":"A field photo whose time looked wrong (future, too old, stale schedule) and the office has not accepted yet."}},"required":["attachmentId","contentType","caption","phaseId","phaseName","day","teamName","punchItem","fieldRequestId","takenBy","capturedAt","receivedAt","sharedWithCustomer","awaitingAcceptance"],"additionalProperties":false},"description":"Newest first."},"truncated":{"type":"boolean","description":"More than 200 match; narrow by phase or day."}},"required":["projectId","name","reference","stage","customerId","customerName","photos","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read a project's progress

> Where a project stands phase by phase, as the project page shows it: each phase's status, crews and days, budget against worked minutes, the percent built last declared, holds and open punch items, plus the project's day n of m. Hours only, no money. Worked minutes are as last recomputed (\`hoursAsOf\`). Company admins with estimate access, as the project page.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/{id}/progress":{"get":{"operationId":"projects.progress.get","tags":["Projects"],"summary":"Read a project's progress","description":"Where a project stands phase by phase, as the project page shows it: each phase's status, crews and days, budget against worked minutes, the percent built last declared, holds and open punch items, plus the project's day n of m. Hours only, no money. Worked minutes are as last recomputed (`hoursAsOf`). Company admins with estimate access, as the project page.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reference":{"type":["string","null"]},"stage":{"type":"string","description":"draft, sent, approved, in_progress, ready_to_close, closed, lost, cancelled."},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"onHold":{"type":"boolean"},"holdReason":{"type":["string","null"]},"holdResumeDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"declaredPct":{"type":["number","null"],"description":"Percent built across the counted phases, weighted by their hours."},"schedule":{"anyOf":[{"type":"object","properties":{"dayNumber":{"type":"integer"},"dayCount":{"type":"integer"},"firstDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"lastDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"nextDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]}},"required":["dayNumber","dayCount","firstDay","lastDay","nextDay"],"additionalProperties":false},{"type":"null"}],"description":"Day n of m over the project's work days; null before approval."},"budgetMinutes":{"type":"number","description":"Minutes."},"workedMinutes":{"type":"number","description":"Minutes."},"budgetUsedPct":{"type":["number","null"]},"phases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ordinal":{"type":"integer","description":"The phase's number on the project page, change-order phases included."},"name":{"type":"string"},"workType":{"type":["string","null"]},"status":{"type":"string","description":"planned, unscheduled, scheduled, in_progress, ready_for_review, reviewed, done."},"billingMode":{"type":"string","description":"fixed or tm (time and materials)."},"changeOrder":{"type":["string","null"],"description":"`CO-3` on a change order's phase; null on the estimate's own."},"pending":{"type":"boolean","description":"A change order's phase not yet signed."},"startedBeforeSigned":{"type":"boolean","description":"A pending change-order phase the project manager started before the customer signed."},"budgetMinutes":{"type":"number","description":"Minutes."},"scheduleMinutes":{"type":"number","description":"The minutes the phase is scheduled against (a T&M phase's estimate)."},"workedMinutes":{"type":"number","description":"Measured labor so far."},"budgetUsedPct":{"type":["number","null"],"description":"Worked minutes as a share of the scheduled minutes, rounded; null with no budget."},"declaredPct":{"type":"number","description":"The percent built the crew or office last declared."},"declaredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declaredBy":{"type":["string","null"]},"unscheduledMinutes":{"type":"number","description":"Minutes."},"firstDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"lastDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"crews":{"type":"array","items":{"type":"object","properties":{"teamId":{"type":"string","format":"uuid"},"teamName":{"type":"string"},"days":{"type":"integer"},"firstDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"lastDay":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]}},"required":["teamId","teamName","days","firstDay","lastDay"],"additionalProperties":false}},"onHold":{"type":"boolean"},"holdReason":{"type":["string","null"]},"openPunchItems":{"type":"integer"},"overBudgetReason":{"type":["string","null"]},"hoursChangedAfterReview":{"type":"boolean"}},"required":["id","ordinal","name","workType","status","billingMode","changeOrder","pending","startedBeforeSigned","budgetMinutes","scheduleMinutes","workedMinutes","budgetUsedPct","declaredPct","declaredAt","declaredBy","unscheduledMinutes","firstDay","lastDay","crews","onHold","holdReason","openPunchItems","overBudgetReason","hoursChangedAfterReview"],"additionalProperties":false}},"hoursAsOf":{"type":"string"}},"required":["projectId","name","reference","stage","customerId","customerName","onHold","holdReason","holdResumeDate","declaredPct","schedule","budgetMinutes","workedMinutes","budgetUsedPct","phases","hoursAsOf"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read a project's checklists, reviews and punch list

> Each phase's task checklist, its review rounds (approved or sent back, by whom, with the reviewer's note and hours) and each round's punch items (open, done, can't do, by whom), newest round first. Photos are facts only (a before or after photo is present). One phase with \`phaseId\`. Company admins with estimate access.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/{id}/punch-list":{"get":{"operationId":"projects.punch_list.get","tags":["Projects"],"summary":"Read a project's checklists, reviews and punch list","description":"Each phase's task checklist, its review rounds (approved or sent back, by whom, with the reviewer's note and hours) and each round's punch items (open, done, can't do, by whom), newest round first. Photos are facts only (a before or after photo is present). One phase with `phaseId`. Company admins with estimate access.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"phaseId","in":"query","required":false,"description":"Only this phase.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reference":{"type":["string","null"]},"stage":{"type":"string","description":"draft, sent, approved, in_progress, ready_to_close, closed, lost, cancelled."},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"onHold":{"type":"boolean"},"holdReason":{"type":["string","null"]},"holdResumeDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"openPunchItems":{"type":"integer"},"phases":{"type":"array","items":{"type":"object","properties":{"phaseId":{"type":"string","format":"uuid"},"phaseName":{"type":"string"},"status":{"type":"string"},"phaseVersion":{"type":"integer","description":"The phase's version; adding a punch item names this."},"checklist":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"note":{"type":["string","null"]},"done":{"type":"boolean"},"doneAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"cantDoReason":{"type":["string","null"]}},"required":["title","note","done","doneAt","cantDoReason"],"additionalProperties":false},"description":"The phase's task checklist as the crew sees it."},"openPunchItems":{"type":"integer"},"rounds":{"type":"array","items":{"type":"object","properties":{"round":{"type":"integer"},"outcome":{"type":["string","null"],"description":"approved or sent_back; null while the round is open."},"open":{"type":"boolean"},"submitted":{"type":"boolean","description":"The crew said the open round's punch list is done."},"reviewer":{"type":["string","null"]},"reviewedAt":{"type":"string","format":"date-time"},"reviewedMinutes":{"type":["number","null"]},"note":{"type":["string","null"]},"milestoneReleased":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","description":"The item's version; a change to it names this."},"title":{"type":"string"},"note":{"type":["string","null"]},"status":{"type":"string","enum":["open","done","cant_do"]},"cantDoReason":{"type":["string","null"]},"doneAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"doneBy":{"type":["string","null"]},"hasBeforePhoto":{"type":"boolean"},"hasAfterPhoto":{"type":"boolean"}},"required":["id","version","title","note","status","cantDoReason","doneAt","doneBy","hasBeforePhoto","hasAfterPhoto"],"additionalProperties":false}}},"required":["round","outcome","open","submitted","reviewer","reviewedAt","reviewedMinutes","note","milestoneReleased","items"],"additionalProperties":false},"description":"Review rounds, newest first, each with its punch items."}},"required":["phaseId","phaseName","status","phaseVersion","checklist","openPunchItems","rounds"],"additionalProperties":false}}},"required":["projectId","name","reference","stage","customerId","customerName","onHold","holdReason","holdResumeDate","openPunchItems","phases"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Find a customer for a project

> Searches customers the way New project does in the app: by name, company, email, phone or a property address, every word matching, most recently updated first, up to 8, each with its active properties. It finds any customer account, including customers who only have projects and customers just created from a lead, which \`GET /v1/customers\` and \`find\_customer\` leave out until they have a job. Use the \`id\` as \`customerId\`, and a property's \`id\` as \`propertyId\`, in \`POST /v1/projects\`. Company admins with estimate access.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`project\_estimate\_edit\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_estimate\\_edit\\_not\\_allowed>), \[\`projects\_read\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#projects\\_read\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","customers:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/customers":{"get":{"operationId":"projects.customers.search","tags":["Projects"],"summary":"Find a customer for a project","description":"Searches customers the way New project does in the app: by name, company, email, phone or a property address, every word matching, most recently updated first, up to 8, each with its active properties. It finds any customer account, including customers who only have projects and customers just created from a lead, which `GET /v1/customers` and `find_customer` leave out until they have a job. Use the `id` as `customerId`, and a property's `id` as `propertyId`, in `POST /v1/projects`. Company admins with estimate access.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`project_estimate_edit_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#project_estimate_edit_not_allowed), [`projects_read_only`](https://docs.shortcutco.com/developers/concepts/errors#projects_read_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"q","in":"query","required":false,"description":"Words from the customer's name, company, email, phone or a property address; every word must match. Leave out for the most recently updated customers.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The customer's id: `customerId` for a new project."},"name":{"type":"string","description":"The company's name, else the person's."},"detail":{"type":"string","description":"The contact person, and the first property's address or the email, to tell matches apart."},"properties":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The property's id: `propertyId` for a new project."},"address":{"type":"string","description":"The property's address."},"sqFootage":{"type":["number","null"],"description":"The property's lawn size in square feet, when known."}},"required":["id","address","sqFootage"],"additionalProperties":false},"description":"The customer's active properties, oldest first, up to 10; only the ones matching when the words name an address."}},"required":["id","name","detail","properties"],"additionalProperties":false},"description":"Up to 8 customers, most recently updated first."}},"required":["customers"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Compare finished install phases of one kind

> Finished phases (reviewed or done) of one kind of work across projects, newest review first, at most 60: hours sold against hours worked, and each signed estimate line's quantity and sell price against what the crews used less returned; \`sameLine\` totals every line sold on more than one of them. Window by review day; default the last 365 days. Hours, quantities and sell prices only, no cost or margin. Company admins with estimate access.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/finished-phases":{"get":{"operationId":"projects.finished_phases.list","tags":["Projects"],"summary":"Compare finished install phases of one kind","description":"Finished phases (reviewed or done) of one kind of work across projects, newest review first, at most 60: hours sold against hours worked, and each signed estimate line's quantity and sell price against what the crews used less returned; `sameLine` totals every line sold on more than one of them. Window by review day; default the last 365 days. Hours, quantities and sell prices only, no cost or margin. Company admins with estimate access.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"workType","in":"query","required":true,"description":"hardscape, planting, drainage, irrigation, grading_seeding, demo, cleanup, other.","schema":{"type":"string","enum":["hardscape","planting","drainage","irrigation","grading_seeding","demo","cleanup","other"]}},{"name":"from","in":"query","required":false,"description":"First review day, YYYY-MM-DD; default 365 days before `to`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Last review day, YYYY-MM-DD; default today.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"workType":{"type":"string"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"phases":{"type":"array","items":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"projectName":{"type":"string"},"reference":{"type":["string","null"]},"customerName":{"type":"string"},"phaseId":{"type":"string","format":"uuid"},"phaseName":{"type":"string"},"status":{"type":"string"},"reviewedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"budgetMinutes":{"type":"number","description":"Hours sold, in minutes."},"workedMinutes":{"type":"number"},"budgetUsedPct":{"type":["number","null"]},"overBudgetReason":{"type":["string","null"]},"lines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"material, labor, equipment, other."},"unit":{"type":["string","null"]},"priceBookItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"sold":{"type":["number","null"],"description":"Quantity on the signed estimate."},"unitPrice":{"type":"number","description":"What one unit sold for, before tax and discount."},"used":{"type":["number","null"],"description":"What the crews logged as used less returned; null for a line nothing is logged against (labor, equipment)."}},"required":["name","kind","unit","priceBookItemId","sold","unitPrice","used"],"additionalProperties":false}}},"required":["projectId","projectName","reference","customerName","phaseId","phaseName","status","reviewedAt","budgetMinutes","workedMinutes","budgetUsedPct","overBudgetReason","lines"],"additionalProperties":false}},"sameLine":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"unit":{"type":["string","null"]},"priceBookItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"jobs":{"type":"integer"},"sold":{"type":"number"},"used":{"type":["number","null"]},"usedPerSoldPct":{"type":["number","null"],"description":"Used as a share of sold across the jobs that logged it."},"unitPriceLow":{"type":"number"},"unitPriceHigh":{"type":"number"}},"required":["name","unit","priceBookItemId","jobs","sold","used","usedPerSoldPct","unitPriceLow","unitPriceHigh"],"additionalProperties":false},"description":"Each line sold on more than one of these phases, matched by price-book item or else by name and unit."},"truncated":{"type":"boolean","description":"More than 60 phases match; narrow the window."}},"required":["workType","from","to","phases","sameLine","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read the install day

> Dispatch's Install view for one day: for each crew its lead and people, and each install phase it works that day in driving order with the project, day n of m, the office's note, a hold or rained-out flag, and hours planned, budgeted and worked (today's open clocks included). Hours only, no money. Default today. Company admins with estimate access and everyone's schedule.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read","jobs:read","visits:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/install-day":{"get":{"operationId":"projects.install_day.get","tags":["Projects"],"summary":"Read the install day","description":"Dispatch's Install view for one day: for each crew its lead and people, and each install phase it works that day in driving order with the project, day n of m, the office's note, a hold or rained-out flag, and hours planned, budgeted and worked (today's open clocks included). Hours only, no money. Default today. Company admins with estimate access and everyone's schedule.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"date","in":"query","required":false,"description":"The day, YYYY-MM-DD; default today.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"asOf":{"type":"string","format":"date-time","description":"Worked minutes count open clocks up to this time."},"crews":{"type":"array","items":{"type":"object","properties":{"teamId":{"type":"string","format":"uuid"},"name":{"type":"string"},"lead":{"type":["string","null"]},"people":{"type":"array","items":{"type":"string"}},"maintenanceVisits":{"type":"integer","description":"Maintenance visits the same crew has that day."},"installs":{"type":"array","items":{"type":"object","properties":{"stopNumber":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The project's place in the crew's day; null on a second phase of the same project."},"projectId":{"type":"string","format":"uuid"},"projectName":{"type":"string"},"reference":{"type":["string","null"]},"customerName":{"type":"string"},"phaseId":{"type":"string","format":"uuid"},"phaseName":{"type":"string"},"changeOrder":{"type":["string","null"]},"startedBeforeSigned":{"type":"boolean"},"dayStatus":{"type":"string","description":"planned, active, done, held."},"dayNumber":{"anyOf":[{"type":"integer"},{"type":"null"}]},"dayCount":{"type":"integer"},"note":{"type":["string","null"],"description":"The office's note for the crew that day."},"holdReason":{"type":["string","null"]},"rainedOut":{"type":"boolean"},"plannedMinutes":{"type":"number"},"budgetMinutes":{"type":"number"},"workedMinutes":{"type":"number","description":"The phase's worked minutes so far, today's open clocks included up to `asOf`."},"clocksRunning":{"type":"integer"},"declaredPct":{"type":"number"}},"required":["stopNumber","projectId","projectName","reference","customerName","phaseId","phaseName","changeOrder","startedBeforeSigned","dayStatus","dayNumber","dayCount","note","holdReason","rainedOut","plannedMinutes","budgetMinutes","workedMinutes","clocksRunning","declaredPct"],"additionalProperties":false}}},"required":["teamId","name","lead","people","maintenanceVisits","installs"],"additionalProperties":false}},"maintenanceOnlyCrews":{"type":"array","items":{"type":"object","properties":{"teamId":{"type":"string","format":"uuid"},"name":{"type":"string"},"visits":{"type":"integer"}},"required":["teamId","name","visits"],"additionalProperties":false}}},"required":["date","today","asOf","crews","maintenanceOnlyCrews"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List the install materials for a day

> The materials for the installs booked on one day (default tomorrow, in the company's time zone): each install phase with a work day that day, its crews, and its materials checklist as the crew card shows it: the quantity sold on the signed estimate, used and returned so far, and what is left. Materials are planned per phase, not per day; truck and shop stock are not recorded. Quantities only, no cost or price. Company admins with estimate access and everyone's schedule.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read","jobs:read","visits:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/install-materials":{"get":{"operationId":"projects.install_materials.list","tags":["Projects"],"summary":"List the install materials for a day","description":"The materials for the installs booked on one day (default tomorrow, in the company's time zone): each install phase with a work day that day, its crews, and its materials checklist as the crew card shows it: the quantity sold on the signed estimate, used and returned so far, and what is left. Materials are planned per phase, not per day; truck and shop stock are not recorded. Quantities only, no cost or price. Company admins with estimate access and everyone's schedule.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"date","in":"query","required":false,"description":"The day, YYYY-MM-DD; default tomorrow.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"phases":{"type":"array","items":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"projectName":{"type":"string"},"reference":{"type":["string","null"]},"customerName":{"type":"string"},"phaseId":{"type":"string","format":"uuid"},"phaseName":{"type":"string"},"workType":{"type":"string"},"crews":{"type":"array","items":{"type":"object","properties":{"teamId":{"type":"string","format":"uuid"},"teamName":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"plannedMinutes":{"type":"number"}},"required":["teamId","teamName","kind","status","plannedMinutes"],"additionalProperties":false}},"materials":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"unit":{"type":"string"},"sold":{"type":["number","null"],"description":"The quantity on the signed estimate; null for a material the crew added from the price book."},"used":{"type":"number"},"returned":{"type":"number"},"left":{"type":["number","null"],"description":"Sold less used plus returned, never below 0; null when nothing was sold."},"addedInField":{"type":"boolean"}},"required":["name","unit","sold","used","returned","left","addedInField"],"additionalProperties":false},"description":"The crew card's materials checklist, in the price book's order."}},"required":["projectId","projectName","reference","customerName","phaseId","phaseName","workType","crews","materials"],"additionalProperties":false}},"basis":{"type":"string"}},"required":["date","phases","basis"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List the install week

> Dispatch's Install week: for each crew, the install phases booked on each working day (project, phase, day n of m, hours, holds) and its booked against capacity minutes, plus the approved install work not yet scheduled (ready, or waiting on the deposit). One or two weeks from the week holding \`date\` (default today). Hours only, no money. Company admins with estimate access and everyone's schedule.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read","jobs:read","visits:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/install-week":{"get":{"operationId":"projects.install_week.list","tags":["Projects"],"summary":"List the install week","description":"Dispatch's Install week: for each crew, the install phases booked on each working day (project, phase, day n of m, hours, holds) and its booked against capacity minutes, plus the approved install work not yet scheduled (ready, or waiting on the deposit). One or two weeks from the week holding `date` (default today). Hours only, no money. Company admins with estimate access and everyone's schedule.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"date","in":"query","required":false,"description":"Any day of the first week; default today.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"weeks","in":"query","required":false,"description":"One week or two; default 1.","schema":{"type":"string","enum":["1","2"]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"dates":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"The working days shown."},"crews":{"type":"array","items":{"type":"object","properties":{"teamId":{"type":"string","format":"uuid"},"name":{"type":"string"},"leadName":{"type":["string","null"]},"people":{"type":"integer"},"installs":{"type":"array","items":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"projectName":{"type":"string"},"reference":{"type":["string","null"]},"phaseId":{"type":"string","format":"uuid"},"phaseName":{"type":"string"},"changeOrder":{"type":["string","null"]},"status":{"type":"string"},"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"dates":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"dayNumber":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Day n of `dayCount` at the bar's first day; null on a held run."},"dayCount":{"type":"integer"},"held":{"type":"boolean"},"holdReason":{"type":["string","null"]},"plannedMinutes":{"type":"number"},"budgetMinutes":{"type":["number","null"]},"workedMinutes":{"type":["number","null"]},"declaredPct":{"type":"number"},"startedBeforeSigned":{"type":"boolean"}},"required":["projectId","projectName","reference","phaseId","phaseName","changeOrder","status","start","end","dates","dayNumber","dayCount","held","holdReason","plannedMinutes","budgetMinutes","workedMinutes","declaredPct","startedBeforeSigned"],"additionalProperties":false}},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"bookedMinutes":{"type":"number"},"capacityMinutes":{"type":"number"},"maintenanceVisits":{"type":"integer"}},"required":["date","bookedMinutes","capacityMinutes","maintenanceVisits"],"additionalProperties":false}}},"required":["teamId","name","leadName","people","installs","days"],"additionalProperties":false}},"notScheduled":{"type":"array","items":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reference":{"type":["string","null"]},"customerName":{"type":"string"},"group":{"type":"string","enum":["ready","waiting_on_deposit"]},"approvedAt":{"type":["string","null"]},"waitingDays":{"anyOf":[{"type":"integer"},{"type":"null"}]},"phases":{"type":"array","items":{"type":"object","properties":{"phaseId":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"unscheduledMinutes":{"type":"number"},"plannedCrew":{"type":["string","null"]}},"required":["phaseId","name","status","unscheduledMinutes","plannedCrew"],"additionalProperties":false}}},"required":["projectId","name","reference","customerName","group","approvedAt","waitingDays","phases"],"additionalProperties":false},"description":"Approved install work with phases not yet on the schedule: ready, or waiting on the deposit."},"notScheduledTruncated":{"type":"boolean"}},"required":["from","to","today","dates","crews","notScheduled","notScheduledTruncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List the price book

> The company's price book as the estimate builder offers it: active items in active categories, in the price book's order, each with its category, kind (material, labor, equipment, other, bundle), unit, sell per unit, tax, production rate and labor minutes per unit, a bundle's parts with their quantities, and what the price book flags as unfinished. Filter by kind, category or words. Sell side only: no cost or markup. Company admins with estimate access.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/price-book":{"get":{"operationId":"projects.price_book.list","tags":["Projects"],"summary":"List the price book","description":"The company's price book as the estimate builder offers it: active items in active categories, in the price book's order, each with its category, kind (material, labor, equipment, other, bundle), unit, sell per unit, tax, production rate and labor minutes per unit, a bundle's parts with their quantities, and what the price book flags as unfinished. Filter by kind, category or words. Sell side only: no cost or markup. Company admins with estimate access.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"kind","in":"query","required":false,"description":"Only items of this kind.","schema":{"type":"string","enum":["material","labor","equipment","other","bundle"]}},{"name":"categoryId","in":"query","required":false,"description":"Only items in this category or its subcategories.","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","required":false,"description":"Only items whose name or category holds these words.","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"limit","in":"query","required":false,"description":"How many items, up to 200. Defaults to 100.","schema":{"type":"integer","minimum":1,"maximum":200,"default":100}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer","description":"Items that match, before `limit`."},"truncated":{"type":"boolean","description":"True when more items match than are listed."},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","format":"uuid"},"name":{"type":"string"},"category":{"type":"string","description":"The category, as \"Parent › Child\" for a subcategory."},"kind":{"type":"string","enum":["material","labor","equipment","other","bundle"]},"unit":{"type":["string","null"],"description":"The unit the item is priced in (sq ft, ton, hr, each); null when the price book has none yet."},"sellPerUnit":{"type":["number","null"],"description":"What the company sells one unit for; null when it cannot be worked out yet."},"taxable":{"type":"boolean"},"productionRate":{"type":["number","null"],"description":"Units a person installs in an hour (labor items)."},"laborMinutesPerUnit":{"type":["number","null"],"description":"Labor minutes for one unit."},"problems":{"type":"array","items":{"type":"string"},"description":"What the price book flags as unfinished on the item (missing_unit, missing_price, missing_production_rate …)."},"parts":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"kind":{"anyOf":[{"type":"string","enum":["material","labor","equipment","other","bundle"]},{"type":"null"}]},"unit":{"type":["string","null"]},"quantityPerUnit":{"type":"number","description":"How many of this part go into one unit of the bundle."}},"required":["itemId","name","kind","unit","quantityPerUnit"],"additionalProperties":false},"description":"A bundle's parts, in order; empty for any other item."}},"required":["itemId","name","category","kind","unit","sellPerUnit","taxable","productionRate","laborMinutesPerUnit","problems","parts"],"additionalProperties":false}}},"required":["total","truncated","items"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List warranties ending

> Projects whose warranty ends between two days, soonest first, at most 100. A warranty starts at the project's closeout and lasts the company's warranty length in Projects settings today (the length a customer was promised is not stored per project). Defaults: from today to 90 days out, in the company's time zone. Company admins with estimate access.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/warranties":{"get":{"operationId":"projects.warranties.list","tags":["Projects"],"summary":"List warranties ending","description":"Projects whose warranty ends between two days, soonest first, at most 100. A warranty starts at the project's closeout and lasts the company's warranty length in Projects settings today (the length a customer was promised is not stored per project). Defaults: from today to 90 days out, in the company's time zone. Company admins with estimate access.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD; default today.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Last day, YYYY-MM-DD; default 90 days after `from`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"warrantyMonths":{"type":"integer"},"lengthBasis":{"type":"string"},"projects":{"type":"array","items":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reference":{"type":["string","null"]},"stage":{"type":"string"},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"warrantyStartsAt":{"type":"string","format":"date-time"},"warrantyEndsAt":{"type":"string","format":"date-time"}},"required":["projectId","name","reference","stage","customerId","customerName","warrantyStartsAt","warrantyEndsAt"],"additionalProperties":false}},"truncated":{"type":"boolean","description":"More than 100 end in the window; narrow it."}},"required":["from","to","warrantyMonths","lengthBasis","projects","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List installs with no maintenance

> Installs closed out between two days, newest first, at most 100, whose customer has no active maintenance job (pending, scheduled or paused) and no maintenance estimate made since the install was approved; an earlier maintenance estimate is listed with the row. Default: the last 365 days, in the company's time zone. Offers made outside Shortcut are not recorded. Company admins with estimate access and everyone's schedule.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`clip\_charge\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_charge\\_not\\_allowed>), \[\`project\_details\_office\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#project\\_details\\_office\\_only>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Projects","description":"A project has a stage, a customer, a reference, and can be on hold. A draft project's estimate (phases, lines and totals) can be built through the API; sending, approving, signing and billing it stay in the app.\n\nFields: [The project object](https://docs.shortcutco.com/developers/reference/objects/project)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["projects:read","estimates:read","jobs:read","visits:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/projects/without-maintenance":{"get":{"operationId":"projects.without_maintenance.list","tags":["Projects"],"summary":"List installs with no maintenance","description":"Installs closed out between two days, newest first, at most 100, whose customer has no active maintenance job (pending, scheduled or paused) and no maintenance estimate made since the install was approved; an earlier maintenance estimate is listed with the row. Default: the last 365 days, in the company's time zone. Offers made outside Shortcut are not recorded. Company admins with estimate access and everyone's schedule.\n\n**Errors specific to this endpoint:** [`clip_charge_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_charge_not_allowed), [`project_details_office_only`](https://docs.shortcutco.com/developers/concepts/errors#project_details_office_only), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"from","in":"query","required":false,"description":"First closeout day, YYYY-MM-DD; default 365 days before `to`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Last closeout day, YYYY-MM-DD; default today.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"projects":{"type":"array","items":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"reference":{"type":["string","null"]},"stage":{"type":"string"},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"closedOutAt":{"type":"string","format":"date-time","description":"When the install's closeout was done (the warranty starts here)."},"workTypes":{"type":"array","items":{"type":"string"}},"earlierMaintenanceEstimates":{"type":"array","items":{"type":"object","properties":{"estimateId":{"type":"string","format":"uuid"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["estimateId","status","createdAt"],"additionalProperties":false},"description":"Maintenance estimates for the customer from before the install was approved, if any."}},"required":["projectId","name","reference","stage","customerId","customerName","closedOutAt","workTypes","earlierMaintenanceEstimates"],"additionalProperties":false}},"basis":{"type":"string"},"truncated":{"type":"boolean","description":"More than 100 match; narrow the window."}},"required":["from","to","projects","basis","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```
