API Reference

files

12 endpoints

POST/api/v1/files/uploads

Initiate Upload

Start an upload and get presigned URLs to send the bytes to.

Returns a single presigned PUT URL for a small file, or one URL per part for a multipart upload. PATCH the returned upload_id once the bytes are there.

The scope required depends on owner_type rather than being declared on the route: uploading org or reward assets demands the org or reward upload scope, not upload:user:write.

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field	Type	Description
owner_type*	enum	What the file will belong to
owner_uuid*	string	UUID of the owning user, organization, activity or reward
file_name*	string
content_type*	string
size_in_bytes*	integer

Responses

200Successful Response

Field

Type

Description

upload_id*

string

upload_type*

string

upload_url

string | null

parts

UploadPartInfo[] | null

array items · UploadPartInfo

Field	Type	Description
part_number*	integer
upload_url*	string
start_byte*	integer
end_byte*	integer

expires_at*

string (date-time)

400Invalid request

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

409Resource already exists

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X POST "https://api.davi.social/api/v1/files/uploads" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

PATCH/api/v1/files/uploads/{upload_id}

Complete Upload

Finalize an upload once the bytes are in place, producing the file.

A multipart upload must send back the part numbers and ETags S3 returned; a simple one sends nothing.

Path parameters

upload_id*

string

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field

Type

Description

parts

CompletedPartInfo[] | null

array items · CompletedPartInfo

Field	Type	Description
part_number*	integer
etag*	string

Responses

200Successful Response

Field	Type	Description
uuid*	string
slug*	string
file_name*	string
content_type*	string
size_in_bytes*	integer
file_url	string \| null

400Invalid request

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

409Resource already exists

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X PATCH "https://api.davi.social/api/v1/files/uploads/{upload_id}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

DELETE/api/v1/files/uploads/{upload_id}

Abort Upload

Abandon a pending upload and clean up anything already sent.

Path parameters

upload_id*

string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
message*	string	Success or status message

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X DELETE "https://api.davi.social/api/v1/files/uploads/{upload_id}" \
  -H "Authorization: Bearer <token>"

GET/api/v1/files/{file_slug}

Get File By Slug

Get a file by its slug.

The only file route not addressed through an owner, because a slug is enough to find one. Authorization therefore runs against whatever the file turns out to belong to.

Path parameters

file_slug*

string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
uuid*	string
slug*	string
file_name*	string
content_type*	string
size_in_bytes*	integer
storage_id*	string
storage_key*	string
storage_bucket*	string
file_url	string \| null
created_at*	string (date-time)
updated_at	string (date-time) \| null

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/files/{file_slug}" \
  -H "Authorization: Bearer <token>"

GET/api/v1/users/{user_uuid}/files

List User Files

List a user's files.

Path parameters

user_uuid*

string | string (uuid)

Query parameters

default_backend	string	default: "primary"
page	integer	default: 1 · ≥ 1
page_size	integer	default: 20 · ≥ 1 · ≤ 100
sort_by	string \| null
sort_order	string	default: "asc"

Responses

200Successful Response

Field

Type

Description

total_items*

integer

Total number of items available

total_pages*

integer

Total number of pages available

current_page*

integer

Current page number

items*

UploadedFileResponse[]

List of items on the current page

array items · UploadedFileResponse

Field	Type	Description
uuid*	string
slug*	string
file_name*	string
content_type*	string
size_in_bytes*	integer
storage_id*	string
storage_key*	string
storage_bucket*	string
file_url	string \| null
created_at*	string (date-time)
updated_at	string (date-time) \| null

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/users/{user_uuid}/files" \
  -H "Authorization: Bearer <token>"

DELETE/api/v1/users/{user_uuid}/files/{file_uuid}

Delete User File

Delete a user's file.

Path parameters

user_uuid*	string \| string (uuid)
file_uuid*	string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
message*	string	Success or status message

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X DELETE "https://api.davi.social/api/v1/users/{user_uuid}/files/{file_uuid}" \
  -H "Authorization: Bearer <token>"

GET/api/v1/organizations/{organization_slug}/files

List Organization Files

List an organization's files.

Path parameters

organization_slug*

string

Query parameters

default_backend	string	default: "primary"
page	integer	default: 1 · ≥ 1
page_size	integer	default: 20 · ≥ 1 · ≤ 100
sort_by	string \| null
sort_order	string	default: "asc"

Responses

200Successful Response

Field

Type

Description

total_items*

integer

Total number of items available

total_pages*

integer

Total number of pages available

current_page*

integer

Current page number

items*

UploadedFileResponse[]

List of items on the current page

array items · UploadedFileResponse

Field	Type	Description
uuid*	string
slug*	string
file_name*	string
content_type*	string
size_in_bytes*	integer
storage_id*	string
storage_key*	string
storage_bucket*	string
file_url	string \| null
created_at*	string (date-time)
updated_at	string (date-time) \| null

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/organizations/{organization_slug}/files" \
  -H "Authorization: Bearer <token>"

DELETE/api/v1/organizations/{organization_slug}/files/{file_uuid}

Delete Organization File

Delete an organization's file.

Path parameters

file_uuid*	string
organization_slug*	string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
message*	string	Success or status message

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X DELETE "https://api.davi.social/api/v1/organizations/{organization_slug}/files/{file_uuid}" \
  -H "Authorization: Bearer <token>"

GET/api/v1/activities/{activity_slug}/files

List Activity Files

List an activity's files.

Path parameters

activity_slug*

string

Query parameters

default_backend	string	default: "primary"
page	integer	default: 1 · ≥ 1
page_size	integer	default: 20 · ≥ 1 · ≤ 100
sort_by	string \| null
sort_order	string	default: "asc"

Responses

200Successful Response

Field

Type

Description

total_items*

integer

Total number of items available

total_pages*

integer

Total number of pages available

current_page*

integer

Current page number

items*

UploadedFileResponse[]

List of items on the current page

array items · UploadedFileResponse

Field	Type	Description
uuid*	string
slug*	string
file_name*	string
content_type*	string
size_in_bytes*	integer
storage_id*	string
storage_key*	string
storage_bucket*	string
file_url	string \| null
created_at*	string (date-time)
updated_at	string (date-time) \| null

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/activities/{activity_slug}/files" \
  -H "Authorization: Bearer <token>"

DELETE/api/v1/activities/{activity_slug}/files/{file_uuid}

Delete Activity File

Delete an activity's file.

Path parameters

activity_slug*	string
file_uuid*	string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
message*	string	Success or status message

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X DELETE "https://api.davi.social/api/v1/activities/{activity_slug}/files/{file_uuid}" \
  -H "Authorization: Bearer <token>"

GET/api/v1/rewards/{reward_slug}/files

List Reward Files

List a reward template's files.

Path parameters

reward_slug*

string

Query parameters

default_backend	string	default: "primary"
page	integer	default: 1 · ≥ 1
page_size	integer	default: 20 · ≥ 1 · ≤ 100
sort_by	string \| null
sort_order	string	default: "asc"

Responses

200Successful Response

Field

Type

Description

total_items*

integer

Total number of items available

total_pages*

integer

Total number of pages available

current_page*

integer

Current page number

items*

UploadedFileResponse[]

List of items on the current page

array items · UploadedFileResponse

Field	Type	Description
uuid*	string
slug*	string
file_name*	string
content_type*	string
size_in_bytes*	integer
storage_id*	string
storage_key*	string
storage_bucket*	string
file_url	string \| null
created_at*	string (date-time)
updated_at	string (date-time) \| null

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/rewards/{reward_slug}/files" \
  -H "Authorization: Bearer <token>"

DELETE/api/v1/rewards/{reward_slug}/files/{file_uuid}

Delete Reward File

Delete a reward template's file.

Path parameters

reward_slug*	string
file_uuid*	string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
message*	string	Success or status message

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X DELETE "https://api.davi.social/api/v1/rewards/{reward_slug}/files/{file_uuid}" \
  -H "Authorization: Bearer <token>"