API reference

Organizations API

List, read, create, and rename the organizations the caller belongs to.

List organizations: GET /v1/organizations
Create an organization: POST /v1/organizations
Get an organization: GET /v1/organizations/{organization_id}
Rename an organization: PATCH /v1/organizations/{organization_id}

List organizations

GET /v1/organizations

API key: Authorization: Bearer vmy_… with preset read_only, use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie.
Who: Any member.

Responses

Status	Description	Body
`200`	—	`OrganizationList`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/organizations" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "items": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "dev",
      "role": "owner",
      "suspended_at": "2026-10-12T05:51:01Z"
    }
  ]
}

Create an organization

POST /v1/organizations

API key: not accepted (403 session_required).
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Any signed-in user.

Request body (application/json, CreateOrganizationRequest)

Field	Type	Required	Description
`name`	`string`	Yes	1-64 characters without control characters or surrounding whitespace; unique (case-insensitively) among the caller's own organizations. 1–64 characters.

Responses

Status	Description	Body
`201`	Created with the caller as owner and a trial wallet	`OrganizationDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	CSRF failure or bearer authentication (`session_required`)	`ProblemDetails`
`409`	`organization_name_taken`: the caller already created one with this name	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`
`429`	`rate_limited`: 5 creations per user per 24 hours, counting the personal organization created at sign-in	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/organizations" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "dev"
}'

Response 201

{
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "role": "owner",
  "suspended_at": "2026-10-12T05:51:01Z"
}

Get an organization

GET /v1/organizations/{organization_id}

API key: Authorization: Bearer vmy_… with preset read_only, use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie.
Who: Any member.

Parameters

Name	In	Type	Required	Description
`organization_id`	path	`string (uuid)`	Yes

Responses

Status	Description	Body
`200`	—	`OrganizationDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`404`	Not a member, or another organization than the API key's	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "role": "owner",
  "suspended_at": "2026-10-12T05:51:01Z"
}

Rename an organization

PATCH /v1/organizations/{organization_id}

API key: not accepted (403 session_required).
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner or Admin.

Parameters

Name	In	Type	Required	Description
`organization_id`	path	`string (uuid)`	Yes

Request body (application/json, UpdateOrganizationRequest)

Field	Type	Required	Description
`name`	`string`	Yes	1–64 characters.

Responses

Status	Description	Body
`200`	—	`OrganizationDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	CSRF failure, bearer authentication (`session_required`), or neither owner nor admin	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	`organization_name_taken`: its creator already has an organization with this name	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X PATCH "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "dev"
}'

Response 200

{
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "role": "owner",
  "suspended_at": "2026-10-12T05:51:01Z"
}