/v1/tasks/{task_id}/photosAuthentication
Bearer API key or Facily session, subject to permissions and facility scope.
Authentication and scopeRequest example
Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.
curl --request POST \
--url 'https://api.staging.facily.ai/v1/tasks/<TASK_ID>/photos' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"declared_size_bytes": 0,
"document_type": "string",
"mime_type": "string",
"title": "string",
"unit_id": "00000000-0000-4000-8000-000000000001"
}'Parameters
task_idpath · stringrequiredFormat: uuid
Request body
application/json · Required
declared_size_bytesintegerrequiredThe file's size in bytes, at most 10,485,760 (10 MB).
document_typestringrequiredThe photo's type: task_photo_proof for a photo that shows the work was done, task_photo_reference for any other photo. A work order also takes task_photo_before and task_photo_after, and an after photo counts toward completing it as a proof photo does. An inspection also takes task_photo_finding, one for each finding, sent with that finding's unit_id.
mime_typestringrequiredThe file's type: image/jpeg, image/png or image/webp.
titlestring | nullA label for the photo, such as its file name, up to 255 characters. Blank means none.
Max length: 255
Show title schema
string | nullA label for the photo, such as its file name, up to 255 characters. Blank means none.
Variant 1: string
stringVariant 2: null
nullunit_idstring | nullFor a task_photo_finding photo, the unit of the inspection finding it belongs to; required there and refused with any other type.
Format: uuid
Show unit_id schema
string | nullFor a task_photo_finding photo, the unit of the inspection finding it belongs to; required there and refused with any other type.
Variant 1: string
stringVariant 2: null
nullResponses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
201Successful Response
{
"data": {
"document_id": "00000000-0000-4000-8000-000000000001",
"expires_at": "2026-10-29T12:00:00Z",
"fields": {},
"upload_url": "string"
},
"meta": {
"request_id": "string"
}
}application/json
dataTaskPhotoUploadGrantResponserequiredWhere the browser uploads the photo, and the photo's id to confirm it with.
Show data schema
document_idstringrequiredThe photo's id. Send it to the confirm route once the file is uploaded.
Format: uuid
expires_atstringrequiredWhen the upload form stops being accepted, 5 minutes after the grant.
Format: date-time
fieldsobjectrequiredThe signed form fields to post before the file.
upload_urlstringrequiredWhere the browser posts the file, as a multipart form with fields.
metaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired400Validation error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired401Unauthenticated
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired403Permission denied
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired404Not found
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired409Business logic error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired503Temporary failure
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired