API Reference

cards

16 endpoints

GET/api/v1/organizations/{organization_slug}/card-models

List Card Models

List card models for an organization.

Returns a paginated list of card models owned by the organization. By default, only active card models are returned. Use include_inactive=true to include deactivated models.

Path parameters

organization_slug*

string

Query parameters

include_inactive	boolean	Include inactive card models in the list default: false
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*

CardModelResponse[]

List of items on the current page

array items · CardModelResponse

Field	Type	Description
uuid*	string
slug*	string	Short, URL-friendly public identifier (nanoid).
name*	string
description	string \| null
organization_uuid	string \| null
front_image_url	string \| null
back_image_url	string \| null
ordering_schema	object \| null
template_data	object \| null	Raw template-kit design document, if the card model was published with one. Opaque, portable payload for rendering/authoring by consumers.
is_active*	boolean
profile_template_uuid	string \| null	UUID of the profile page template attached to this card model. Must be platform-owned or owned by the same organization as the card model. When NULL, cards using this model do not auto-generate a profile.
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}/card-models" \
  -H "Authorization: Bearer <token>"

POST/api/v1/organizations/{organization_slug}/card-models

Create Card Model

Create a new card model for an organization.

Card models are reusable card designs with front/back images that can be assigned to managed cards. Organizations can create multiple card models for different purposes (e.g., member cards, VIP cards, event cards).

Path parameters

organization_slug*

string

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field	Type	Description
name*	string	Display name for the card design max length 255
description	string \| null	Optional description of the card design max length 2000
front_image_file_uuid	string \| string (uuid) \| null	UUID of the uploaded file for the front image
back_image_file_uuid	string \| string (uuid) \| null	UUID of the uploaded file for the back image
ordering_schema	object \| null	JSON schema for ordering/printing workflows
template_data	object \| null	Raw template-kit design document (the source template). Stored as an opaque, portable payload so consumers can fetch and render the design; carries its own format_version.
profile_template_uuid	string \| string (uuid) \| null	UUID of the profile page template attached to this card model. Must be platform-owned or owned by the same organization as the card model. When NULL, cards using this model do not auto-generate a profile.
is_active	boolean	Whether the card model is active and can be assigned to cards default: true

Responses

200Successful Response

Field	Type	Description
uuid*	string
slug*	string	Short, URL-friendly public identifier (nanoid).
name*	string
description	string \| null
organization_uuid	string \| null
front_image_url	string \| null
back_image_url	string \| null
ordering_schema	object \| null
template_data	object \| null	Raw template-kit design document, if the card model was published with one. Opaque, portable payload for rendering/authoring by consumers.
is_active*	boolean
profile_template_uuid	string \| null	UUID of the profile page template attached to this card model. Must be platform-owned or owned by the same organization as the card model. When NULL, cards using this model do not auto-generate a profile.
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

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/organizations/{organization_slug}/card-models" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

GET/api/v1/organizations/{organization_slug}/card-models/{card_model_slug}

Get Card Model

Get a card model.

Returns the card model details including presigned URLs for the front and back images (if set).

Path parameters

card_model_slug*	string
organization_slug*	string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
uuid*	string
slug*	string	Short, URL-friendly public identifier (nanoid).
name*	string
description	string \| null
organization_uuid	string \| null
front_image_url	string \| null
back_image_url	string \| null
ordering_schema	object \| null
template_data	object \| null	Raw template-kit design document, if the card model was published with one. Opaque, portable payload for rendering/authoring by consumers.
is_active*	boolean
profile_template_uuid	string \| null	UUID of the profile page template attached to this card model. Must be platform-owned or owned by the same organization as the card model. When NULL, cards using this model do not auto-generate a profile.
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/organizations/{organization_slug}/card-models/{card_model_slug}" \
  -H "Authorization: Bearer <token>"

PATCH/api/v1/organizations/{organization_slug}/card-models/{card_model_slug}

Update Card Model

Update a card model.

Only the fields provided in the request body will be updated. Set is_active=false to deactivate a card model (soft disable).

Path parameters

card_model_slug*	string
organization_slug*	string

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field	Type	Description
name	string \| null	Display name for the card design max length 255
description	string \| null	Optional description of the card design max length 2000
front_image_file_uuid	string \| string (uuid) \| null	UUID of the uploaded file for the front image
back_image_file_uuid	string \| string (uuid) \| null	UUID of the uploaded file for the back image
ordering_schema	object \| null	JSON schema for ordering/printing workflows
template_data	object \| null	Raw template-kit design document (the source template). Stored as an opaque, portable payload so consumers can fetch and render the design; carries its own format_version.
profile_template_uuid	string \| string (uuid) \| null	UUID of the profile page template attached to this card model. Must be platform-owned or owned by the same organization as the card model. When NULL, cards using this model do not auto-generate a profile.
is_active	boolean \| null	Whether the card model is active and can be assigned to cards

Responses

200Successful Response

Field	Type	Description
uuid*	string
slug*	string	Short, URL-friendly public identifier (nanoid).
name*	string
description	string \| null
organization_uuid	string \| null
front_image_url	string \| null
back_image_url	string \| null
ordering_schema	object \| null
template_data	object \| null	Raw template-kit design document, if the card model was published with one. Opaque, portable payload for rendering/authoring by consumers.
is_active*	boolean
profile_template_uuid	string \| null	UUID of the profile page template attached to this card model. Must be platform-owned or owned by the same organization as the card model. When NULL, cards using this model do not auto-generate a profile.
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

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/organizations/{organization_slug}/card-models/{card_model_slug}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

DELETE/api/v1/organizations/{organization_slug}/card-models/{card_model_slug}

Delete Card Model

Delete a card model.

Deleting a card model will unassign it from any managed cards that reference it (their card_model_uuid will be set to NULL).

Consider deactivating the card model instead by setting is_active=false to preserve history while preventing new assignments.

Path parameters

card_model_slug*	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}/card-models/{card_model_slug}" \
  -H "Authorization: Bearer <token>"

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

List Organization Cards

List the cards in the organization's inventory.

Path parameters

organization_slug*

string

Query parameters

page	integer	default: 1 · ≥ 1
page_size	integer	default: 20 · ≥ 1 · ≤ 100
sort_by	string \| null
sort_order	string	default: "desc"
identifier	string \| null	Return only the card with exactly this identifier. How a caller turns a scanned card into the uuid the rest of this resource is addressed by.
search	string \| null	Return cards whose identifier contains this text. A search, not a lookup — use `identifier` for an exact match.
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*

CardResponse[]

List of items on the current page

array items · CardResponse

Field

Type

Description

uuid*

string

identifier*

string

name

string | null

card_type*

CardType

is_primary

boolean

default: false

is_frozen*

boolean

organization_uuid

string | null

front_image_url

string | null

Resolved front image: custom override > card model > None

back_image_url

string | null

Back image from card model design

custom_front_image_url

string | null

User's custom front image override (if set)

profile_page_uuid

string | null

card_model_uuid

string | null

membership_tier_uuid

string | null

card_model

CardModelSummaryResponse | null

object · CardModelSummaryResponse

Field	Type	Description
uuid*	string
name*	string
front_image_url	string \| null
back_image_url	string \| null
is_active*	boolean

membership_tier

MembershipTierSummaryResponse | null

object · MembershipTierSummaryResponse

Field	Type	Description
uuid*	string
slug*	string
name*	string

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

POST/api/v1/organizations/{organization_slug}/cards

Assign Organization Cards

Take manufactured cards into the organization's inventory.

Each identifier must already exist — cards are minted once by fulfillment, and an organization takes one rather than creating it. An identifier the platform never made is refused, which is what stops one tenant from claiming another's batch or blocking a range it does not own.

Partial success by design: one bad identifier in a batch does not reject the rest, and each failure comes back with its reason. Assigning a card the organization already holds is a no-op, so a retried batch is safe.

Path parameters

organization_slug*

string

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field

Type

Description

cards*

AssignOrgCardRequest[]

Cards to take into inventory

array items · AssignOrgCardRequest

Field	Type	Description
identifier*	string	The card's identifier, as manufactured. Must already exist in platform inventory: an organization takes a card, it does not mint one.
membership_tier_uuid	string \| string (uuid) \| null	Optional membership tier to auto-assign when card is claimed

membership_tier_uuid

string | string (uuid) | null

Default membership tier for all cards (can be overridden per card)

Responses

200Successful Response

Field

Type

Description

assigned

CardResponse[]

Cards now in the organization's inventory

array items · CardResponse

Field

Type

Description

uuid*

string

identifier*

string

name

string | null

card_type*

CardType

is_primary

boolean

default: false

is_frozen*

boolean

organization_uuid

string | null

front_image_url

string | null

Resolved front image: custom override > card model > None

back_image_url

string | null

Back image from card model design

custom_front_image_url

string | null

User's custom front image override (if set)

profile_page_uuid

string | null

card_model_uuid

string | null

membership_tier_uuid

string | null

card_model

CardModelSummaryResponse | null

object · CardModelSummaryResponse

Field	Type	Description
uuid*	string
name*	string
front_image_url	string \| null
back_image_url	string \| null
is_active*	boolean

membership_tier

MembershipTierSummaryResponse | null

object · MembershipTierSummaryResponse

Field	Type	Description
uuid*	string
slug*	string
name*	string

created_at*

string (date-time)

updated_at

string (date-time) | null

failed

object[]

Cards that could not be assigned, each with the reason

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/organizations/{organization_slug}/cards" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

GET/api/v1/organizations/{organization_slug}/cards/{card_uuid}

Get Organization Card

Read one card from the organization's inventory.

Path parameters

card_uuid*	string
organization_slug*	string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field

Type

Description

uuid*

string

identifier*

string

name

string | null

card_type*

CardType

is_primary

boolean

default: false

is_frozen*

boolean

organization_uuid

string | null

front_image_url

string | null

Resolved front image: custom override > card model > None

back_image_url

string | null

Back image from card model design

custom_front_image_url

string | null

User's custom front image override (if set)

profile_page_uuid

string | null

card_model_uuid

string | null

membership_tier_uuid

string | null

card_model

CardModelSummaryResponse | null

object · CardModelSummaryResponse

Field	Type	Description
uuid*	string
name*	string
front_image_url	string \| null
back_image_url	string \| null
is_active*	boolean

membership_tier

MembershipTierSummaryResponse | null

object · MembershipTierSummaryResponse

Field	Type	Description
uuid*	string
slug*	string
name*	string

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/organizations/{organization_slug}/cards/{card_uuid}" \
  -H "Authorization: Bearer <token>"

PATCH/api/v1/organizations/{organization_slug}/cards/{card_uuid}

Update Organization Card

Update a card in the organization's inventory.

Covers the card model, the membership tier assignment and the registry freeze. To remove a value, pass an empty string for that field.

The frozen flag here is the registry freeze and is dominant: a card frozen by its issuer stays frozen however its holder sets their own flag on PATCH /cards/{card_uuid}.

Takes both card:org:manage and card:org:freeze because freezing folded into this endpoint: the permission is checked per endpoint rather than per field, and no role separates the two scopes anyway.

Path parameters

card_uuid*	string
organization_slug*	string

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field	Type	Description
name	string \| string \| null	Friendly name for the card. Set to empty string to remove. max length 255
card_model_uuid	string \| string \| string (uuid) \| null	UUID of the card model (design template) to assign. Set to empty string to remove.
membership_tier_uuid	string \| string \| string (uuid) \| null	UUID of the membership tier to auto-assign when claimed. Set to empty string to remove.
frozen	boolean \| null	Whether the card is frozen. Freezing is a state the card is in, not an event: set it true or false and omit to leave it alone.

Responses

200Successful Response

Field

Type

Description

uuid*

string

identifier*

string

name

string | null

card_type*

CardType

is_primary

boolean

default: false

is_frozen*

boolean

organization_uuid

string | null

front_image_url

string | null

Resolved front image: custom override > card model > None

back_image_url

string | null

Back image from card model design

custom_front_image_url

string | null

User's custom front image override (if set)

profile_page_uuid

string | null

card_model_uuid

string | null

membership_tier_uuid

string | null

card_model

CardModelSummaryResponse | null

object · CardModelSummaryResponse

Field	Type	Description
uuid*	string
name*	string
front_image_url	string \| null
back_image_url	string \| null
is_active*	boolean

membership_tier

MembershipTierSummaryResponse | null

object · MembershipTierSummaryResponse

Field	Type	Description
uuid*	string
slug*	string
name*	string

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

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/organizations/{organization_slug}/cards/{card_uuid}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

DELETE/api/v1/organizations/{organization_slug}/cards/{card_uuid}

Release Organization Card

Return an unclaimed card to platform inventory.

The registry row survives: the identifier belongs to the physical object and outlives any organization holding it. Refused once someone has claimed the card, since releasing it would strip their membership silently — the holder unclaims first.

Path parameters

card_uuid*	string
organization_slug*	string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field

Type

Description

uuid*

string

identifier*

string

name

string | null

card_type*

CardType

is_primary

boolean

default: false

is_frozen*

boolean

organization_uuid

string | null

front_image_url

string | null

Resolved front image: custom override > card model > None

back_image_url

string | null

Back image from card model design

custom_front_image_url

string | null

User's custom front image override (if set)

profile_page_uuid

string | null

card_model_uuid

string | null

membership_tier_uuid

string | null

card_model

CardModelSummaryResponse | null

object · CardModelSummaryResponse

Field	Type	Description
uuid*	string
name*	string
front_image_url	string \| null
back_image_url	string \| null
is_active*	boolean

membership_tier

MembershipTierSummaryResponse | null

object · MembershipTierSummaryResponse

Field	Type	Description
uuid*	string
slug*	string
name*	string

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 DELETE "https://api.davi.social/api/v1/organizations/{organization_slug}/cards/{card_uuid}" \
  -H "Authorization: Bearer <token>"

GET/api/v1/cards

List Cards

List the cards the caller holds.

Query parameters

identifier	string \| null	Return only the card with exactly this identifier. How a caller turns a scanned card into the uuid the rest of this resource is addressed by.
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*

CardResponse[]

List of items on the current page

array items · CardResponse

Field

Type

Description

uuid*

string

identifier*

string

name

string | null

card_type*

CardType

is_primary

boolean

default: false

is_frozen*

boolean

organization_uuid

string | null

front_image_url

string | null

Resolved front image: custom override > card model > None

back_image_url

string | null

Back image from card model design

custom_front_image_url

string | null

User's custom front image override (if set)

profile_page_uuid

string | null

card_model_uuid

string | null

membership_tier_uuid

string | null

card_model

CardModelSummaryResponse | null

object · CardModelSummaryResponse

Field	Type	Description
uuid*	string
name*	string
front_image_url	string \| null
back_image_url	string \| null
is_active*	boolean

membership_tier

MembershipTierSummaryResponse | null

object · MembershipTierSummaryResponse

Field	Type	Description
uuid*	string
slug*	string
name*	string

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

POST/api/v1/cards

Provision Card

Give the caller a virtual card if they hold none at all.

A repair path, not the normal way to get a card. Signing up provisions one alongside the primary wallet, and a physical-card holder gets theirs by claiming; this exists for the account where neither happened.

Idempotent: 201 when a card is created, 200 with the existing one otherwise. "Holds none at all" is the test — someone holding a claimed physical card is not card-less and gets that card back, not a second one.

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

201Successful Response

Field

Type

Description

uuid*

string

identifier*

string

name

string | null

card_type*

CardType

is_primary

boolean

default: false

is_frozen*

boolean

organization_uuid

string | null

front_image_url

string | null

Resolved front image: custom override > card model > None

back_image_url

string | null

Back image from card model design

custom_front_image_url

string | null

User's custom front image override (if set)

profile_page_uuid

string | null

card_model_uuid

string | null

membership_tier_uuid

string | null

card_model

CardModelSummaryResponse | null

object · CardModelSummaryResponse

Field	Type	Description
uuid*	string
name*	string
front_image_url	string \| null
back_image_url	string \| null
is_active*	boolean

membership_tier

MembershipTierSummaryResponse | null

object · MembershipTierSummaryResponse

Field	Type	Description
uuid*	string
slug*	string
name*	string

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

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

POST/api/v1/cards/claim

Claim Card

Take possession of a card, binding it to the caller's wallet.

Keyed on the identifier because that is all a caller has after tapping a card. The card must already be registered — an identifier the platform never made is not claimable — which is what gives the check something to check against.

If the card carries a membership tier and the caller is not already a member of the issuing organization, a membership is created. The card's design template, if it has one, is rendered into a profile.

First claimant wins: knowing the identifier is what takes the card, so a card is claimable until someone claims it. Rate limited to the expensive bucket.

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field	Type	Description
identifier*	string	The card's identifier — its NFC serial or QR value. This is the one card operation keyed on the identifier rather than the uuid, because it is all a caller has after tapping a card they do not yet hold.

Responses

200Successful Response

Field

Type

Description

card*

CardResponse

The claimed card

object · CardResponse

Field

Type

Description

uuid*

string

identifier*

string

name

string | null

card_type*

CardType

is_primary

boolean

default: false

is_frozen*

boolean

organization_uuid

string | null

front_image_url

string | null

Resolved front image: custom override > card model > None

back_image_url

string | null

Back image from card model design

custom_front_image_url

string | null

User's custom front image override (if set)

profile_page_uuid

string | null

card_model_uuid

string | null

membership_tier_uuid

string | null

card_model

CardModelSummaryResponse | null

object · CardModelSummaryResponse

Field	Type	Description
uuid*	string
name*	string
front_image_url	string \| null
back_image_url	string \| null
is_active*	boolean

membership_tier

MembershipTierSummaryResponse | null

object · MembershipTierSummaryResponse

Field	Type	Description
uuid*	string
slug*	string
name*	string

created_at*

string (date-time)

updated_at

string (date-time) | null

wallet_address*

string

Wallet address linked to the card

membership_created

boolean

Whether a new membership was created as part of claiming

default: false

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/cards/claim" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

GET/api/v1/cards/{card_uuid}

Get Card

Read one of the caller's cards.

Path parameters

card_uuid*

string

Responses

200Successful Response

Field

Type

Description

uuid*

string

identifier*

string

name

string | null

card_type*

CardType

is_primary

boolean

default: false

is_frozen*

boolean

organization_uuid

string | null

front_image_url

string | null

Resolved front image: custom override > card model > None

back_image_url

string | null

Back image from card model design

custom_front_image_url

string | null

User's custom front image override (if set)

profile_page_uuid

string | null

card_model_uuid

string | null

membership_tier_uuid

string | null

card_model

CardModelSummaryResponse | null

object · CardModelSummaryResponse

Field	Type	Description
uuid*	string
name*	string
front_image_url	string \| null
back_image_url	string \| null
is_active*	boolean

membership_tier

MembershipTierSummaryResponse | null

object · MembershipTierSummaryResponse

Field	Type	Description
uuid*	string
slug*	string
name*	string

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/cards/{card_uuid}" \
  -H "Authorization: Bearer <token>"

PATCH/api/v1/cards/{card_uuid}

Update Card

Update how the caller holds this card.

Renaming, choosing the primary card and freezing are all states the card is in rather than events, so they are fields here instead of four separate action endpoints.

Takes both card:manage and card:freeze: the permission is checked per endpoint rather than per field, and no role separates the two.

Path parameters

card_uuid*

string

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field

Type

Description

name

string | string | null

Friendly name for the card. Set to empty string to remove.

max length 255

is_primary

boolean | null

Make this the caller's primary card, the identity anchor whose profile answers a default lookup. Only `true` is meaningful: a primary card is unset by naming a different one.

frozen

boolean | null

Whether the holder has frozen this card. The issuer keeps a separate registry freeze, and a card is frozen if either is set.

Responses

200Successful Response

Field

Type

Description

uuid*

string

identifier*

string

name

string | null

card_type*

CardType

is_primary

boolean

default: false

is_frozen*

boolean

organization_uuid

string | null

front_image_url

string | null

Resolved front image: custom override > card model > None

back_image_url

string | null

Back image from card model design

custom_front_image_url

string | null

User's custom front image override (if set)

profile_page_uuid

string | null

card_model_uuid

string | null

membership_tier_uuid

string | null

card_model

CardModelSummaryResponse | null

object · CardModelSummaryResponse

Field	Type	Description
uuid*	string
name*	string
front_image_url	string \| null
back_image_url	string \| null
is_active*	boolean

membership_tier

MembershipTierSummaryResponse | null

object · MembershipTierSummaryResponse

Field	Type	Description
uuid*	string
slug*	string
name*	string

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

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/cards/{card_uuid}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

DELETE/api/v1/cards/{card_uuid}

Unclaim Card

Release a card from the caller's account.

The registry row survives for a physical or organization-issued card — the identifier belongs to the object, so the card returns to being claimable rather than ceasing to exist. A self-provisioned virtual card, which nobody else can ever hold, is destroyed.

The primary card cannot be released; name a different primary first.

Path parameters

card_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/cards/{card_uuid}" \
  -H "Authorization: Bearer <token>"