Project files API

REST endpoints for project files in ServFlo: 6 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

Operation	Endpoint	Risk
A project's files	`GET /organizations/{organizationId}/projects/{projectId}/files`	`read`
Start uploading a project file	`POST /organizations/{organizationId}/projects/{projectId}/files`	`write`
Finish uploading a project file	`POST /organizations/{organizationId}/projects/{projectId}/files/{projectFileId}/confirm`	`write`
Add a project file (content in the request)	`POST /organizations/{organizationId}/projects/{projectId}/files/content`	`write`
Share a project file or change its category	`PATCH /organizations/{organizationId}/projects/{projectId}/files/{projectFileId}`	`sensitive`
Delete a project file	`DELETE /organizations/{organizationId}/projects/{projectId}/files/{projectFileId}`	`sensitive`

A project's files

GET /organizations/{organizationId}/projects/{projectId}/files

Plans, permits, contracts, photos and lien waivers with who they are shared with and 10-minute URLs. Technicians see those shared with the crew. Read-only.


Permission	`projects.read` (Owner, Admin, Dispatcher, Technician, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`projectFiles_list` (toolset `projects`)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string	Yes	The project (GET /projects).
`category`	query	enum	No	One of `PLAN`, `PERMIT`, `CONTRACT`, `PHOTO`, `SELECTION`, `LIEN_WAIVER`, `OTHER`.
`dailyLogId`	query	string	No
`phaseId`	query	string	No

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/files" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string
`category`	enum	One of `PLAN`, `PERMIT`, `CONTRACT`, `PHOTO`, `SELECTION`, `LIEN_WAIVER`, `OTHER`.
`fileName`	string
`contentType`	string
`sharedWithCrew`	boolean
`sharedWithSubs`	boolean
`sharedWithCustomer`	boolean
`url`	string	A 10-minute download URL.

Start uploading a project file

POST /organizations/{organizationId}/projects/{projectId}/files

Step 1 of a browser upload: records the file and returns a signed URL to PUT it to (5 minutes, same Content-Type), then POST …/files/{projectFileId}/confirm. Up to 25 MB. Sharing defaults by category (plans: everyone; photos: the crew). API keys and AI apps use POST …/files/content.


Permission	`projects.field` (Owner, Admin, Dispatcher, Technician)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`projectFiles_createUpload` (toolset `projects`)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string	Yes	The project (GET /projects).

Request body

Field	Type	Required	Description
`fileName`	string	Yes	Up to 255 characters.
`contentType`	string	Yes	Up to 100 characters.
`sizeBytes`	integer	Yes	At least 1.
`category`	enum	No	PLAN, PERMIT, CONTRACT, PHOTO, SELECTION, LIEN_WAIVER or OTHER (the crew adds PHOTO or OTHER). One of `PLAN`, `PERMIT`, `CONTRACT`, `PHOTO`, `SELECTION`, `LIEN_WAIVER`, `OTHER`. Default `OTHER`.
`phaseId`	string or null	No
`dailyLogId`	string or null	No	A photo of this daily log.
`subPaymentId`	string or null	No	A lien waiver for this payment to a subcontractor.
`sharedWithCrew`	boolean	No
`sharedWithSubs`	boolean	No
`sharedWithCustomer`	boolean	No

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/files" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"string","contentType":"string","sizeBytes":1}'

Response

201: the answer's fields

Field	Type	Description
`file`	object
`file.id`	string
`file.fileName`	string
`uploadUrl`	string

Finish uploading a project file

POST /organizations/{organizationId}/projects/{projectId}/files/{projectFileId}/confirm

Step 2: the PUT finished; the file is listed from now on.


Permission	`projects.field` (Owner, Admin, Dispatcher, Technician)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`projectFiles_confirm` (toolset `projects`)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string	Yes	The project (GET /projects).
`projectFileId`	path	string	Yes

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/files/{projectFileId}/confirm" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`category`	enum	One of `PLAN`, `PERMIT`, `CONTRACT`, `PHOTO`, `SELECTION`, `LIEN_WAIVER`, `OTHER`.
`fileName`	string
`contentType`	string
`sharedWithCrew`	boolean
`sharedWithSubs`	boolean
`sharedWithCustomer`	boolean
`url`	string	A 10-minute download URL.

Add a project file (content in the request)

POST /organizations/{organizationId}/projects/{projectId}/files/content

Adds a plan, permit, contract, photo or lien waiver in one call: send contentBase64 or a public sourceUrl (up to 10 MB). Returns the file with a 10-minute URL.


Permission	`projects.field` (Owner, Admin, Dispatcher, Technician)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`projectFiles_upload` (toolset `projects`)

Parameters

Name	In	Type	Required	Description
`projectId`	path	string	Yes	The project (GET /projects).

Request body

Field	Type	Required	Description
`category`	enum	No	PLAN, PERMIT, CONTRACT, PHOTO, SELECTION, LIEN_WAIVER or OTHER (the crew adds PHOTO or OTHER). One of `PLAN`, `PERMIT`, `CONTRACT`, `PHOTO`, `SELECTION`, `LIEN_WAIVER`, `OTHER`. Default `OTHER`.
`phaseId`	string or null	No
`dailyLogId`	string or null	No	A photo of this daily log.
`subPaymentId`	string or null	No	A lien waiver for this payment to a subcontractor.
`sharedWithCrew`	boolean	No
`sharedWithSubs`	boolean	No
`sharedWithCustomer`	boolean	No
`fileName`	string	No	The file's name, e.g. receipt.jpg (default: from the URL, else 'file'). Up to 500 characters.
`contentType`	string	No	MIME type, e.g. image/jpeg or application/pdf. Optional: taken from a data: URL, the URL's answer or the file's first bytes. Up to 200 characters.
`contentBase64`	string	No	The file's bytes as base64 (a data: URL is accepted too). Up to 10 MB. Give this or sourceUrl.
`sourceUrl`	string (uri)	No	A public http(s) URL ServFlo downloads the file from (up to 10 MB, 20 s, 3 redirects; private and internal addresses are refused). Give this or contentBase64. Up to 2000 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/files/content" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"OTHER","phaseId":"phase_id","dailyLogId":"dailyLog_id"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string
`category`	enum	One of `PLAN`, `PERMIT`, `CONTRACT`, `PHOTO`, `SELECTION`, `LIEN_WAIVER`, `OTHER`.
`fileName`	string
`contentType`	string
`sharedWithCrew`	boolean
`sharedWithSubs`	boolean
`sharedWithCustomer`	boolean
`url`	string	A 10-minute download URL.

Share a project file or change its category

PATCH /organizations/{organizationId}/projects/{projectId}/files/{projectFileId}

EXPOSES TO THE CUSTOMER OR SUBS when switched on: who the file is shared with (crew, subcontractors' links, the customer's portal), its category and phase.


Permission	`projects.write` (Owner, Admin, Dispatcher)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`projectFiles_update` (toolset `projects`)
Approval	Over MCP, this tool asks for your OK first (in the AI app when it supports it, otherwise in ServFlo). See Approvals.

Parameters

Name	In	Type	Required	Description
`projectId`	path	string	Yes	The project (GET /projects).
`projectFileId`	path	string	Yes

Request body

Field	Type	Required	Description
`category`	enum	No	One of `PLAN`, `PERMIT`, `CONTRACT`, `PHOTO`, `SELECTION`, `LIEN_WAIVER`, `OTHER`.
`phaseId`	string or null	No
`sharedWithCrew`	boolean	No
`sharedWithSubs`	boolean	No
`sharedWithCustomer`	boolean	No

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/files/{projectFileId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"PLAN","phaseId":"phase_id","sharedWithCrew":true}'

Response

200: the answer's fields

Field	Type	Description
`id`	string
`category`	enum	One of `PLAN`, `PERMIT`, `CONTRACT`, `PHOTO`, `SELECTION`, `LIEN_WAIVER`, `OTHER`.
`fileName`	string
`contentType`	string
`sharedWithCrew`	boolean
`sharedWithSubs`	boolean
`sharedWithCustomer`	boolean
`url`	string	A 10-minute download URL.

Delete a project file

DELETE /organizations/{organizationId}/projects/{projectId}/files/{projectFileId}

Destructive: deletes the project file for everyone (crew, subs and the customer stop seeing it).


Permission	`projects.write` (Owner, Admin, Dispatcher)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`projectFiles_delete` (toolset `projects`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

Name	In	Type	Required	Description
`projectId`	path	string	Yes	The project (GET /projects).
`projectFileId`	path	string	Yes

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/files/{projectFileId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`ok`	true

On this page