API Reference

users

9 endpoints

GET/api/v1/profiles

List My Profiles

List the profiles the caller owns.

Bounded by how many profiles a person can own, so it returns one page.

Query parameters

default_backend

string

default: "primary"

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*

OwnedProfileSummary[]

List of items on the current page

array items · OwnedProfileSummary

Field

Type

Description

uuid*

string

profile_name

string | null

profile.data.name — may be empty. Frontend falls back to template_name then 'Untitled Profile'.

template_name

string | null

Name of the template that spawned this profile, if still joinable.

is_primary

boolean

default: false

linked_cards

OwnedProfileLinkedCard[]

array items · OwnedProfileLinkedCard

Field	Type	Description
card_uuid*	string
identifier*	string
name	string \| null	Friendly name from card_connections.name, if set.

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/profiles" \
  -H "Authorization: Bearer <token>"

GET/api/v1/profiles/me

Get My Profile

Get the caller's own profile.

A locked profile is returned rather than suppressed, so the owner's UI can render the locked shell. The public read of the same profile hides it.

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field

Type

Description

imageUrl

string

default: ""

name

string

default: ""

first_name

string

default: ""

last_name

string

default: ""

shortDescription

string

default: ""

longDescription

string

default: ""

callToAction

CallToAction | null

object · CallToAction

Field	Type	Description
type*	enum
label*	string
url*	string

currentRole

CurrentRole | null

object · CurrentRole

Field	Type	Description
title*	string
company*	string

customBackground

CustomBackground | null

object · CustomBackground

Field	Type	Description
background	string \| null
backgroundColor	string \| null
backgroundImage	string \| null
backgroundPosition	string \| null
backgroundSize	string \| null
backgroundRepeat	string \| null
backgroundAttachment	string \| null

avatarFrame

string | null

socialLinks

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

links

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

longDescriptionContent

object[]

stickers

object[]

profile_page_uuid

string | null

UUID of the profile page (for use in save-contact flows)

is_locked

boolean

True when the profile was issued by an organization and the owner's membership in that org is inactive. Derived at read time.

default: false

primary_card_uid

string | null

Identifier of the owner's primary card — the `uid` in /c/{uid} URLs. Lets the profile page advertise the card+json discovery link (/c/{uid}/json). NULL for bearer profiles and owners with no primary card.

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/profiles/me" \
  -H "Authorization: Bearer <token>"

PATCH/api/v1/profiles/me

Update My Profile

Update the caller's profile (partial update).

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field

Type

Description

profile_uuid

string | string (uuid) | null

UUID of the profile to update. If not provided, updates the user's default profile.

imageUrl

string | null

name

string | null

first_name

string | null

last_name

string | null

shortDescription

string | null

longDescription

string | null

callToAction

CallToAction | null

object · CallToAction

Field	Type	Description
type*	enum
label*	string
url*	string

currentRole

CurrentRole | null

object · CurrentRole

Field	Type	Description
title*	string
company*	string

customBackground

CustomBackground | null

object · CustomBackground

Field	Type	Description
background	string \| null
backgroundColor	string \| null
backgroundImage	string \| null
backgroundPosition	string \| null
backgroundSize	string \| null
backgroundRepeat	string \| null
backgroundAttachment	string \| null

socialLinks

ProfileLink[] | null

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

links

ProfileLink[] | null

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

longDescriptionContent

object[] | null

Full list replacement when provided; null leaves existing value.

stickers

object[] | null

Full list replacement when provided; null leaves existing value.

Responses

200Successful Response

Field	Type	Description
uuid*	string
username	string \| null
data	ProfileData \| object
is_claimed	boolean	default: false
created_at*	string (date-time)
updated_at	string (date-time) \| null
longDescriptionContent	object[]
stickers	object[]

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

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 PATCH "https://api.davi.social/api/v1/profiles/me" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

GET/api/v1/profiles/public/count

Count Public Profiles

Count publicly-indexable profiles (claimed, has a username, not locked).

Powers the sitemap index: the generator divides this by its page size to know how many sub-sitemaps to emit, without fetching every profile.

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
count*	integer	Number of publicly-indexable profiles.

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/profiles/public/count" \
  -H "Authorization: Bearer <token>"

GET/api/v1/profiles/public

List Public Profiles

One page of publicly-indexable profile usernames for a sub-sitemap.

A bulk export rather than a list endpoint, which is why it takes offset/limit instead of the usual paging: a sitemap generator reading the whole set 100 rows at a time would issue thousands of requests. Stably ordered, so each page is deterministic across runs.

Query parameters

offset	integer	default: 0 · ≥ 0
limit	integer	default: 10000 · ≥ 1 · ≤ 50000
default_backend	string	default: "primary"

Responses

200Successful Response

Field

Type

Description

profiles

PublicProfileSitemapEntry[]

array items · PublicProfileSitemapEntry

Field	Type	Description
username*	string
updated_at	string (date-time) \| null	Last profile edit — used as the sitemap <lastmod>.

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/profiles/public" \
  -H "Authorization: Bearer <token>"

GET/api/v1/profiles/{profile_uuid}

Get My Profile By Uuid

Get one of the caller's own profiles by uuid.

Scoped to the caller's own: a profile belonging to someone else is not readable here, only through the public read on its owner.

Path parameters

profile_uuid*

string (uuid)

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field

Type

Description

imageUrl

string

default: ""

name

string

default: ""

first_name

string

default: ""

last_name

string

default: ""

shortDescription

string

default: ""

longDescription

string

default: ""

callToAction

CallToAction | null

object · CallToAction

Field	Type	Description
type*	enum
label*	string
url*	string

currentRole

CurrentRole | null

object · CurrentRole

Field	Type	Description
title*	string
company*	string

customBackground

CustomBackground | null

object · CustomBackground

Field	Type	Description
background	string \| null
backgroundColor	string \| null
backgroundImage	string \| null
backgroundPosition	string \| null
backgroundSize	string \| null
backgroundRepeat	string \| null
backgroundAttachment	string \| null

avatarFrame

string | null

socialLinks

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

links

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

longDescriptionContent

object[]

stickers

object[]

profile_page_uuid

string | null

UUID of the profile page (for use in save-contact flows)

is_locked

boolean

True when the profile was issued by an organization and the owner's membership in that org is inactive. Derived at read time.

default: false

primary_card_uid

string | 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/profiles/{profile_uuid}" \
  -H "Authorization: Bearer <token>"

GET/api/v1/users/{username}/profile

Get User Profile

Get a user's profile page.

Public by design — this is what a shared profile link resolves to, so any caller holding profile:read may read it and no ownership check applies. A locked profile is suppressed here even though its owner can still see it.

Carries profile_page_uuid, which is what POST /contacts takes to save the person behind the page.

Path parameters

username*

string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field

Type

Description

imageUrl

string

default: ""

name

string

default: ""

first_name

string

default: ""

last_name

string

default: ""

shortDescription

string

default: ""

longDescription

string

default: ""

callToAction

CallToAction | null

object · CallToAction

Field	Type	Description
type*	enum
label*	string
url*	string

currentRole

CurrentRole | null

object · CurrentRole

Field	Type	Description
title*	string
company*	string

customBackground

CustomBackground | null

object · CustomBackground

Field	Type	Description
background	string \| null
backgroundColor	string \| null
backgroundImage	string \| null
backgroundPosition	string \| null
backgroundSize	string \| null
backgroundRepeat	string \| null
backgroundAttachment	string \| null

avatarFrame

string | null

socialLinks

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

links

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

longDescriptionContent

object[]

stickers

object[]

profile_page_uuid

string | null

UUID of the profile page (for use in save-contact flows)

is_locked

boolean

True when the profile was issued by an organization and the owner's membership in that org is inactive. Derived at read time.

default: false

primary_card_uid

string | 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/users/{username}/profile" \
  -H "Authorization: Bearer <token>"

GET/api/v1/users/search

Search Users

Search users by username, first name, last name, or email.

Finds a person to act on within an organization — someone to invite, or a recipient to issue something to. exclude_members chooses between those two readings: invites want existing members left out, while issuing to a recipient wants them in, since members (the caller included) are the likely targets.

organization_uuid is required: it is what makes this endpoint authorizable. org:members:manage is an ownership-deferred scope, so it is only enforced once a resource is named — without an organization to check against, the scope declaration is inert and any authenticated token could search every user by email, name or username. The membership check is run against the caller's current role rather than the one embedded in an org-scoped token, matching the other member-management endpoints.

Query parameters

q*	string	Search query min length 2 · max length 100
organization_uuid*	string	Organization the search is being run for. Scopes the caller's authorization.
limit	integer	Max results default: 10 · ≥ 1 · ≤ 50
exclude_members	boolean	Omit users who already belong to `organization_uuid`. Defaults to true, which suits picking someone to invite; pass false to search everyone, including the caller. default: true
default_backend	string	default: "primary"

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*

UserSearchSuggestion[]

List of items on the current page

array items · UserSearchSuggestion

Field	Type	Description
uuid*	string
username	string \| null
email	string \| null
first_name	string \| null
last_name	string \| null
avatar_image_file_url	string \| 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/search" \
  -H "Authorization: Bearer <token>"

GET/api/v1/users/{username}

Get User

Get a user by username.

Readable by any caller holding user:read. UserResponse carries only what a user publishes about themselves; their own account record is at /users/me.

Path parameters

username*

string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
uuid*	string
username*	string
first_name*	string
last_name	string \| null
account_type*	enum
avatar_image_file_uuid	string \| null
avatar_image_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/users/{username}" \
  -H "Authorization: Bearer <token>"