API Reference

organizations

5 endpoints

/api/v1/organizations

GET/api/v1/organizations

List Organizations

List organizations the current user is a member of or owns.

For org-scoped tokens, returns only the scoped organization.

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*

OrganizationResponse[]

List of items on the current page

array items · OrganizationResponse

Field	Type	Description
uuid*	string
name*	string
slug*	string	The organization's address in `/api/v1/organizations/{slug}`. Derived from the name when the organization is created and fixed from then on, so renaming does not move it. Organizations created before slugs were derived carry a random one.
description	string \| null
website	string \| null
logo_image_file_uuid	string \| null
logo_image_file_url	string \| null
timezone	string \| null	IANA zone this organization operates in. Its activities' sessions are set and shown on this clock unless an activity declares its own
owner_uuid	string \| null	User UUID of the organization owner (the OWNER-role member)
role	enum \| null	Current user's role in this organization (populated in user-context listings)
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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

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

POST/api/v1/organizations

Create Organization

Create a new organization.

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field	Type	Description
name*	string	min length 1 · max length 100
description	string \| null	max length 500
owner_uuid*	string \| string (uuid)	UUID of the organization owner

Responses

200Successful Response

Field	Type	Description
uuid*	string
name*	string
slug*	string	The organization's address in `/api/v1/organizations/{slug}`. Derived from the name when the organization is created and fixed from then on, so renaming does not move it. Organizations created before slugs were derived carry a random one.
description	string \| null
website	string \| null
logo_image_file_uuid	string \| null
logo_image_file_url	string \| null
timezone	string \| null	IANA zone this organization operates in. Its activities' sessions are set and shown on this clock unless an activity declares its own
owner_uuid	string \| null	User UUID of the organization owner (the OWNER-role member)
role	enum \| null	Current user's role in this organization (populated in user-context listings)
created_at*	string (date-time)
updated_at	string (date-time) \| 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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

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

GET/api/v1/organizations/{organization_slug}

Get Organization

Get an organization by slug (or uuid, until v1 is frozen).

Path parameters

organization_slug*

string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
uuid*	string
name*	string
slug*	string	The organization's address in `/api/v1/organizations/{slug}`. Derived from the name when the organization is created and fixed from then on, so renaming does not move it. Organizations created before slugs were derived carry a random one.
description	string \| null
website	string \| null
logo_image_file_uuid	string \| null
logo_image_file_url	string \| null
timezone	string \| null	IANA zone this organization operates in. Its activities' sessions are set and shown on this clock unless an activity declares its own
owner_uuid	string \| null	User UUID of the organization owner (the OWNER-role member)
role	enum \| null	Current user's role in this organization (populated in user-context listings)
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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

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

PATCH/api/v1/organizations/{organization_slug}

Update Organization

Update an organization.

Requires an org-scoped token for the target organization.

Path parameters

organization_slug*

string

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field	Type	Description
name	string \| null	min length 1 · max length 100
description	string \| null	max length 500
website	string \| null	max length 200
logo_image_file_uuid	string \| string (uuid) \| null
timezone	string \| null	IANA zone this organization operates in, e.g. `Asia/Manila`. Its activities' sessions are set and shown on this clock unless an activity declares its own. Times are always stored and returned in UTC; this says which wall clock they mean. Null leaves it undeclared, and a client falls back to the viewer's own

Responses

200Successful Response

Field	Type	Description
uuid*	string
name*	string
slug*	string	The organization's address in `/api/v1/organizations/{slug}`. Derived from the name when the organization is created and fixed from then on, so renaming does not move it. Organizations created before slugs were derived carry a random one.
description	string \| null
website	string \| null
logo_image_file_uuid	string \| null
logo_image_file_url	string \| null
timezone	string \| null	IANA zone this organization operates in. Its activities' sessions are set and shown on this clock unless an activity declares its own
owner_uuid	string \| null	User UUID of the organization owner (the OWNER-role member)
role	enum \| null	Current user's role in this organization (populated in user-context listings)
created_at*	string (date-time)
updated_at	string (date-time) \| 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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

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

DELETE/api/v1/organizations/{organization_slug}

Delete Organization

Delete an organization.

Requires an org-scoped token for the target organization.

Path parameters

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

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
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

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