Members API

The Members API lets you manage who has access to your organizations and projects. You can invite new members, assign roles, update permissions, and remove members programmatically.

Roles

Comvi uses a unified role hierarchy across organizations and projects:

Role	Description
`owner`	Full control, including billing and member management
`manager`	Manage projects, members, and settings
`editor`	Edit translations and keys
`translator`	Translate content in assigned languages
`viewer`	Read-only access

Organization Members

List organization members

Returns all members of an organization with their roles.

GET /api/v1/organizations/:orgId/members

Path parameters

Parameter	Type	Required	Description
`orgId`	`integer`	Yes	Organization ID

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/organizations/1/members

Example response

[
  {
    "userId": 42,
    "email": "jane@example.com",
    "name": "Jane Smith",
    "role": "owner",
    "joinedAt": "2025-01-10T08:00:00Z",
    "accessScope": "organization",
    "projectCount": 5
  },
  {
    "userId": 43,
    "email": "bob@example.com",
    "name": "Bob Johnson",
    "role": "translator",
    "joinedAt": "2025-02-15T14:30:00Z",
    "accessScope": "project",
    "projectCount": 2
  }
]

Response fields

Field	Type	Description
`userId`	`integer`	User ID
`email`	`string`	Member’s email address
`name`	`string`	Member’s display name
`role`	`string`	Organization role (`owner`, `manager`, `editor`, `translator`, `viewer`)
`joinedAt`	`string`	ISO 8601 timestamp of when the member joined
`accessScope`	`string`	`"organization"` (access to all projects) or `"project"` (access to specific projects only)
`projectCount`	`integer`	Number of projects the member has access to

Invite organization member

Invite a user to the organization by email. If the user already has a Comvi account, they are added directly. Otherwise, an invitation email is sent.

POST /api/v1/organizations/:orgId/members/invite

Path parameters

Parameter	Type	Required	Description
`orgId`	`integer`	Yes	Organization ID

Request body

Field	Type	Required	Description
`email`	`string`	Yes	Email address of the person to invite
`role`	`string`	Yes	Role to assign (`owner`, `manager`, `editor`, `translator`, `viewer`)
`projectId`	`integer`	No	Assign to a specific project on join
`languageRestrictions`	`string[]`	No	Restrict to specific locale codes (e.g., `["fr", "de"]`)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "translator@example.com",
    "role": "translator",
    "projectId": 5,
    "languageRestrictions": ["fr", "de"]
  }' \
  https://api.comvi.io/api/v1/organizations/1/members/invite

Example response

{
  "id": 12,
  "email": "translator@example.com",
  "role": "translator",
  "projectId": 5,
  "languageRestrictions": ["fr", "de"],
  "token": "abc123...",
  "expiresAt": "2025-04-01T08:00:00Z",
  "createdAt": "2025-03-25T08:00:00Z"
}

Update member role

Update an organization member’s role. You cannot change the role of the last remaining owner.

PATCH /api/v1/organizations/:orgId/members/:userId

Path parameters

Parameter	Type	Required	Description
`orgId`	`integer`	Yes	Organization ID
`userId`	`integer`	Yes	User ID of the member to update

Request body

Field	Type	Required	Description
`role`	`string`	Yes	New role to assign

Example request

curl -X PATCH \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"role": "editor"}' \
  https://api.comvi.io/api/v1/organizations/1/members/43

Response

Returns 204 No Content on success.

Remove member

Remove a user from the organization. This also removes them from all projects within the organization.

DELETE /api/v1/organizations/:orgId/members/:userId

Path parameters

Parameter	Type	Required	Description
`orgId`	`integer`	Yes	Organization ID
`userId`	`integer`	Yes	User ID of the member to remove

Example request

curl -X DELETE \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/organizations/1/members/43

Response

Returns 204 No Content on success.

Project Members

List project members

Returns all members of a project with their organization and project roles.

GET /api/v1/projects/:projectId/members

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/projects/5/members

Example response

[
  {
    "userId": 42,
    "email": "jane@example.com",
    "name": "Jane Smith",
    "organizationRole": "owner",
    "projectRole": "owner",
    "languageRestrictions": null,
    "addedAt": "2025-01-10T08:00:00Z"
  },
  {
    "userId": 44,
    "email": "maria@example.com",
    "name": "Maria Garcia",
    "organizationRole": "translator",
    "projectRole": "translator",
    "languageRestrictions": ["es", "pt"],
    "addedAt": "2025-03-01T12:00:00Z"
  }
]

Response fields

Field	Type	Description
`userId`	`integer`	User ID
`email`	`string`	Member’s email address
`name`	`string`	Member’s display name
`organizationRole`	`string`	The member’s role at the organization level
`projectRole`	`string`	The member’s role at the project level
`languageRestrictions`	`string[] \| null`	Locale codes the member can work with, or `null` for all languages
`addedAt`	`string`	ISO 8601 timestamp of when the member was added to the project

Add project member

Add an existing organization member to a project. The user must already belong to the organization.

POST /api/v1/projects/:projectId/members

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID

Request body

Field	Type	Required	Description
`userId`	`integer`	Yes	User ID of the organization member to add
`role`	`string`	Yes	Project role (`owner`, `manager`, `editor`, `translator`, `viewer`)
`languageRestrictions`	`string[]`	No	Restrict to specific locale codes

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 44,
    "role": "translator",
    "languageRestrictions": ["es", "pt"]
  }' \
  https://api.comvi.io/api/v1/projects/5/members

Response

Returns 201 Created on success.

Update project member

Update a project member’s role or language restrictions.

PATCH /api/v1/projects/:projectId/members/:userId

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID
`userId`	`integer`	Yes	User ID of the member to update

Request body

Field	Type	Required	Description
`role`	`string`	Yes	New project role
`languageRestrictions`	`string[]`	No	Updated locale code restrictions, or `null` for all languages

Example request

curl -X PATCH \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "editor",
    "languageRestrictions": null
  }' \
  https://api.comvi.io/api/v1/projects/5/members/44

Response

Returns 204 No Content on success.

Remove project member

Remove a user from a project. This does not remove them from the organization.

DELETE /api/v1/projects/:projectId/members/:userId

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID
`userId`	`integer`	Yes	User ID of the member to remove

Example request

curl -X DELETE \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/projects/5/members/44

Response

Returns 204 No Content on success.

Errors

Status	Error Code	Description
`400`	`CANNOT_REMOVE_LAST_OWNER`	Cannot remove or demote the last owner of an organization
`400`	`ROLE_HIERARCHY_VIOLATION`	Cannot assign a role higher than your own
`403`	`FORBIDDEN`	Missing required permission (`organization.manage_members` or `project.manage_members`)
`404`	`USER_NOT_FOUND`	The specified user does not exist
`404`	`ORGANIZATION_NOT_FOUND`	The specified organization does not exist
`404`	`PROJECT_NOT_FOUND`	The specified project does not exist
`409`	`USER_ALREADY_IN_ORGANIZATION`	The user is already a member of this organization
`409`	`INVITATION_ALREADY_SENT`	An invitation has already been sent to this email

Next Steps

Roles & Permissions Understand the full permission model and role hierarchy.

Organizations API Create and manage organizations.

Projects API Manage projects that members are assigned to.

Error Reference Complete list of error codes.