Users
This API endpoint provides you with full CRUD operations on users, including assigning them to teams and managing cross-platform identity mapping.
Search Users
Retrieves a paginated list of users with optional filters and sorting
HTTP request
GET https://public-api.linearb.io/api/v1/users
Query parameter
| Parameter name | Value | Description |
|---|---|---|
| offset | integer | Number of users to skip. (The default is 0) |
| page_size | integer | Number of users per page. (The default is 50. Minimum: 1, Maximum: 50) |
| order_by | string | Sort field. (Available values: name, email) |
| order_dir | string | Sort of direction. (Available values: ASC, DESC) |
| search_by_field | string | Search field. (Available values: id, name, email) |
| search_term | string | Text to filter users. (Min length: 1, Max length: 100) |
| user_role | string | Filter by role. (Available values: admin, editor, viewer, basic) |
| include_user_children | boolean | Include sub-users. (The default is false) |
Responses
200 - Successful Response
{
"total": 0,
"items": [
{
"id": 0,
"organization_id": "string",
"name": "string",
"email": "string",
"avatar_url": "string",
"extra": {},
"created_at": "string",
"updated_at": "string",
"deleted_at": "string",
"team_membership": [
{}
],
"user_type_id": 0,
"connected_users": {
"platform_users": [
{}
],
"contributors": [
{}
]
},
"permissions": {}
}
]
}
400 - Bad Request
401 - Unauthorized
405 - Method Not Allowed
422 - Validation Error
500 - Internal Server Error
Create Users
Creates a one or more new users in LinearB.
HTTP request
POST https://public-api.linearb.io/api/v1/users
Body parameters (for each user)
| Parameter name | Value | Description |
|---|---|---|
| name (required) | string | The user’s full name |
| email (required) | string | The user’s email address. |
| permission.role | string | User role. One of: admin, editor, viewer, basic |
| permission.team_scopes | array | List of team names the user can access. |
| view_dev_coaching | boolean | Controls whether the user can view developer coaching content. |
| team_membership | array | Array of objects with name and joined_at fields for teams. |
| custom_info.extra_emails | array | Optional array of alternate emails. |
| custom_info.extra_ids | array | Optional array of additional IDs. |
Example
[
{
"name": "ada lovelace",
"email": "ada@lovelace.io",
"permission": {
"role": "basic",
"team_scopes": [
"All Teams"
],
"view_dev_coaching": false
},
"team_membership": [
{
"name": "Ada engineering",
"joined_at": "2025-01-01"
}
],
"custom_info": {
"extra_emails": [
"user@lovelace.io"
],
"extra_ids": [
"1234567890"
]
}
}
]
Responses
200 - Successful Response
{
"job_id": "string",
"message": "string"
}
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
405 - Method Not Allowed
409 - Conflict
422 - Validation Error
500 - Internal Server Error
504 - Gateway Timeout
Update User
Updates an existing user by ID. Any omitted fields will remain unchanged.
HTTP request
PATCH https://public-api.linearb.io/api/v1/users/{user_id}
Body parameters
| Parameter name | Value | Description |
|---|---|---|
| name (required) | string | The user’s full name |
| email (required) | string | The user’s email address. |
| permission.role | string | User role. One of: admin, editor, viewer, basic |
| permission.team_scopes | array | List of team names the user can access. |
| view_dev_coaching | boolean | Controls whether the user can view developer coaching content. |
| team_membership | array | Array of objects with name and joined_at fields for teams. |
| custom_info.extra_emails | array | Optional array of alternate emails. |
| custom_info.extra_ids | array | Optional array of additional IDs. |
Responses
200 - Successful Response
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
405 - Method Not Allowed
409 - Conflict
422 - Validation Error
500 - Internal Server Error
504 - Gateway Timeout
Delete User
Deletes a user identified by their user ID.
HTTP request
DELETE https://public-api.linearb.io/api/v1/users/{user_id}
Responses
200 - Successful Response
204 - Successful Response
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
405 - Method Not Allowed
409 - Conflict
422 - Validation Error
500 - Internal Server Error
504 - Gateway Timeout
Unmerge Users
Splits one or more users out of a unified user. Each listed user becomes a standalone unified user again. The primary user cannot be unmerged directly - set a new primary first with Set Primary User.
HTTP request
POST https://public-api.linearb.io/api/v1/users/{user_id}/unmerge
Path parameters
| Parameter name | Value | Description |
|---|---|---|
| user_id (required) | integer | Unified user object ID |
Body parameters
| Parameter name | Value | Description |
|---|---|---|
| users (required) | array of integers | IDs of the merged users to split back out |
Example
{
"users": [
1002
]
}
Responses
200 - Successful Response
{
"user_id": 0,
"primary_user": 0,
"merged_users": [
0
],
"unmerged_users": [
0
]
}
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
405 - Method Not Allowed
409 - Conflict
422 - Validation Error
500 - Internal Server Error
504 - Gateway Timeout
Set Primary User
Changes which user is the primary of a unified user's merge group. The requested user must already be merged under the unified user.
HTTP request
POST https://public-api.linearb.io/api/v1/users/{user_id}/primary-user
Path parameters
| Parameter name | Value | Description |
|---|---|---|
| user_id (required) | integer | Unified user object ID (Minimum: 1) |
Body parameters
| Parameter name | Value | Description |
|---|---|---|
| primary_user (required) | integer | ID of the already-merged user to promote to primary |
Example
{
"primary_user": 1003
}
Responses
200 - Successful Response
{
"user_id": 0,
"primary_user": 0,
"merged_users": [
0
]
}
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
405 - Method Not Allowed
409 - Conflict
422 - Validation Error
500 - Internal Server Error
504 - Gateway Timeout
Classify Users
Bulk-applies bot and metrics-exclusion classification flags to up to 25 users at once. Each user must resolve to a live Git contributor to be classified. Every requested user ID that is absent from the skipped map in the response was applied - the flags are not echoed back.
Flags are always set to the absolute value you send, never toggled, so retrying a request is safe.
Note
On a 502, some users may already have been classified - flags are applied one contributor at a time, so a mid-flight failure can leave a partial result. Retry the same request to complete it.
HTTP request
PATCH https://public-api.linearb.io/api/v1/users/classification
Body parameters
| Parameter name | Value | Description |
|---|---|---|
| users (required) | object | Map of user ID (a positive integer) to the flags to set for that user. 1 to 25 entries; each entry must set at least one flag. |
| apply_on_history | boolean | Whether to also back-fill historical metrics for the affected users. (Default: false) |
Flags (for each user)
| Parameter name | Value | Description |
|---|---|---|
| is_bot | boolean | Whether this user should be classified as a bot. |
| is_excluded_from_metrics | boolean | Whether this user should be excluded from metrics. |
Both flags are optional, so you can set just one.
Example
{
"apply_on_history": false,
"users": {
"42": {
"is_excluded_from_metrics": true
},
"500": {
"is_bot": true
}
}
}
Responses
200 - Successful Response
{
"backfill_history": "not_requested",
"skipped": {
"43": "not_a_git_contributor",
"44": "platform_user",
"99": "not_found"
}
}
| Field | Description |
|---|---|
| skipped | Map of user ID to the reason it was not classified. not_a_git_contributor - the user has no live Git identity platform_user - a non-Git login, not a contributor not_found - unknown ID, or its Git identity was removed while the request was processed |
| backfill_history | not_requested - apply_on_history was false in_progress - a metrics back-fill was triggered for the classified users failed - publishing the back-fill failed null - no back-fill decision was reached, for example because nothing was eligible |
400 - Bad Request (fewer than 1 or more than 25 users, or a user with no flag set)
401 - Unauthorized
403 - Forbidden
404 - Not Found
405 - Method Not Allowed
409 - Conflict
422 - Validation Error
500 - Internal Server Error
502 - Bad Gateway
504 - Gateway Timeout