Users (New)

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: 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