Workspaces

A workspace is one veterinary clinic in Vetnio. It scopes every clinical resource; a user can belong to several workspaces with a different role in each.

Guides:Data model Authentication

The workspace object

A workspace the authenticated user belongs to, with the user's role in it.

Attributes

idstringrequired
Identifier of the workspace (veterinary clinic), generated by Vetnio as three lowercase words joined by hyphens. Pass it as the workspaceId path parameter of every workspace-scoped endpoint.
namestringrequired
Display name of the clinic, as set by its admins. An empty string if no name was ever set.
roleenumrequired
The authenticated user's own membership role in this workspace. Roles are cumulative and decide which endpoints the user may call:
- member — clinician access: consultations, recordings, notes, patients and VetsGPT.
- admin — everything a member can do, plus member management, billing, workspace settings and the workspace data-export endpoints.
- superadmin — everything an admin can do, plus deleting the workspace and changing other superadmins' roles. The creator of a workspace starts as its superadmin, and a workspace always keeps at least one.
phoneCallIntegrationEnabledbooleanoptional
Whether the clinic receives phone calls into Vetnio through a telephony integration. Use it to show phone-call features only for clinics that have them. Always present in practice.
revenueRecoveryEnabledbooleanoptional
Whether revenue recovery (suggestions for billable items missed in a consultation) is enabled for the clinic. Use it to show those features only where they are switched on. Always present in practice.

The workspace object

{
  "id": "furunculotic-loud-chihuahua",
  "name": "Riverside Animal Clinic",
  "role": "admin",
  "phoneCallIntegrationEnabled": false,
  "revenueRecoveryEnabled": false
}

Create a workspace

POST/workspaces

Creates a new workspace (veterinary clinic) from a name and country code, and makes the caller its superadmin. Before responding it also records the caller's acceptance of Vetnio's Terms of Service, Privacy Policy and Data Processing Agreement, creates the workspace's default note templates and a billing customer, and may link the clinic to an organization that matches the caller's email domain or lists the clinic on its roster. Failures in those follow-up steps are logged and do not fail the request. The free trial does not start here; it starts with the workspace's first consultation or first VetsGPT conversation. Not idempotent: every successful call creates another workspace. A user may normally create only one workspace (accounts enabled for multi-clinic administration can create up to 200); beyond that the request fails with a generic 500 error. Accepts a session or a personal API key.

AcceptsPersonal key

Request body

namestringrequired
Display name of the clinic, shown in the workspace switcher, on invoices and on PDF letterheads. Not checked for uniqueness or length; an empty string is accepted.
countryCodestringrequired
Two-letter ISO 3166-1 alpha-2 country code of the clinic, for example se, de or us (matched case-insensitively). It sets regional defaults such as the audio retention policy (12 months for Germany, Austria and Switzerland) and becomes the billing address country. Stored as sent and not validated, so send a real code.

Returns

idstringrequired
Identifier of the newly created workspace. Use it as workspaceId in subsequent workspace-scoped calls, for example to create consultations.

Errors

400: The request is malformed or failed validation.
401: The API key is missing, invalid or revoked.
403: The key is valid but may not perform this action on this resource.
500: Something went wrong on Vetnio's side.

Request

curl -X POST "https://vetnio.com/api/v2/workspaces" \
  -H "Authorization: Bearer $VETNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Riverside Animal Clinic",
  "countryCode": "se"
}'

Response

{
  "id": "appreciable-cardboard-monkey"
}

List workspaces

GET/workspaces

Returns every workspace (veterinary clinic) the authenticated user is a direct member of, with their role in each. Use it to find the workspaceId for workspace-scoped endpoints and to decide which of them the user may call. The list is not paginated and not sorted; sort client-side if needed. Organization admins can also open their organization's clinics without being members, but those clinics are not listed here. Accepts a session or a personal API key; organization and workspace keys get 403.

AcceptsPersonal key

Returns

workspacesarray of objectsrequired
Workspaces where the user is a direct member, in no guaranteed order. Clinics the user can only reach as an organization admin, locked clinics, clinics being deleted or merged, and clinics blocked by an IP allowlist for the caller's address are not included.
Show child attributes
- idstringrequired
  Identifier of the workspace (veterinary clinic), generated by Vetnio as three lowercase words joined by hyphens. Pass it as the workspaceId path parameter of every workspace-scoped endpoint.
- namestringrequired
  Display name of the clinic, as set by its admins. An empty string if no name was ever set.
- roleenumrequired
  The authenticated user's own membership role in this workspace. Roles are cumulative and decide which endpoints the user may call:
  
  member — clinician access: consultations, recordings, notes, patients and VetsGPT.
  
  admin — everything a member can do, plus member management, billing, workspace settings and the workspace data-export endpoints.
  
  superadmin — everything an admin can do, plus deleting the workspace and changing other superadmins' roles. The creator of a workspace starts as its superadmin, and a workspace always keeps at least one.
- phoneCallIntegrationEnabledbooleanoptional
  Whether the clinic receives phone calls into Vetnio through a telephony integration. Use it to show phone-call features only for clinics that have them. Always present in practice.
- revenueRecoveryEnabledbooleanoptional
  Whether revenue recovery (suggestions for billable items missed in a consultation) is enabled for the clinic. Use it to show those features only where they are switched on. Always present in practice.

Errors

400: The request is malformed or failed validation.
401: The API key is missing, invalid or revoked.
403: The key is valid but may not perform this action on this resource.
404: The resource does not exist or is not visible to this key.
500: Something went wrong on Vetnio's side.

Request

curl "https://vetnio.com/api/v2/workspaces" \
  -H "Authorization: Bearer $VETNIO_API_KEY"

Response

{
  "workspaces": [
    {
      "id": "demo-north-clinic",
      "name": "DEMO North Clinic",
      "role": "admin",
      "phoneCallIntegrationEnabled": false,
      "revenueRecoveryEnabled": false
    },
    {
      "id": "demo-central-clinic",
      "name": "DEMO Central Clinic",
      "role": "admin",
      "phoneCallIntegrationEnabled": false,
      "revenueRecoveryEnabled": false
    },
    {
      "id": "demo-south-clinic",
      "name": "DEMO South Clinic",
      "role": "admin",
      "phoneCallIntegrationEnabled": false,
      "revenueRecoveryEnabled": false
    }
  ]
}

curl -X POST "https://vetnio.com/api/v2/workspaces" \ -H "Authorization: Bearer $VETNIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Riverside Animal Clinic", "countryCode": "se" }'

{ "workspaces": [ { "id": "demo-north-clinic", "name": "DEMO North Clinic", "role": "admin", "phoneCallIntegrationEnabled": false, "revenueRecoveryEnabled": false }, { "id": "demo-central-clinic", "name": "DEMO Central Clinic", "role": "admin", "phoneCallIntegrationEnabled": false, "revenueRecoveryEnabled": false }, { "id": "demo-south-clinic", "name": "DEMO South Clinic", "role": "admin", "phoneCallIntegrationEnabled": false, "revenueRecoveryEnabled": false } ] }