Project Users API Reference

This guide provides detailed information about the Project Users API endpoints for managing team members and their permissions.

Authentication

All project user endpoints require authentication using a User Authentication Token. Additionally, you must be an admin or owner of the project to invite or remove users.

bash

Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN

For more information about authentication, see the Authentication Guide.

List Project Users

Retrieve a list of all users (team members) in a project.

http

GET /api/v1/projects/:project_uuid/project_users
Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN

Example with curl:

bash

curl -X GET "https://app.uptinio.com/api/v1/projects/PRJ123456789/project_users" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN" \
  -H "Content-Type: application/json"

Path Parameters

Parameter	Type	Description
project_uuid	string	The UUID of the project

Response

json

[
  {
    "id": 1,
    "role": "owner",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "user": {
      "email": "owner@example.com",
      "name": "John Doe",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    "project": {
      "uuid": "PRJ123456789",
      "name": "My Team",
      "api_token": "abc123def456...",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "is_current": true
    }
  },
  {
    "id": 2,
    "role": "admin",
    "created_at": "2024-01-05T00:00:00Z",
    "updated_at": "2024-01-05T00:00:00Z",
    "user": {
      "email": "admin@example.com",
      "name": "Jane Smith",
      "created_at": "2024-01-05T00:00:00Z",
      "updated_at": "2024-01-05T00:00:00Z"
    },
    "project": {
      "uuid": "PRJ123456789",
      "name": "My Team",
      "api_token": "abc123def456...",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "is_current": true
    }
  },
  {
    "id": 3,
    "role": "collaborator",
    "created_at": "2024-01-10T00:00:00Z",
    "updated_at": "2024-01-10T00:00:00Z",
    "user": {
      "email": "collaborator@example.com",
      "name": "Bob Johnson",
      "created_at": "2024-01-10T00:00:00Z",
      "updated_at": "2024-01-10T00:00:00Z"
    },
    "project": {
      "uuid": "PRJ123456789",
      "name": "My Team",
      "api_token": "abc123def456...",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "is_current": true
    }
  }
]

Response Fields

Field	Type	Description
id	integer	Unique identifier for the project user relationship
role	string	User's role in the project: `owner`, `admin`, or `collaborator`
created_at	string	ISO 8601 timestamp of when the user was added to the project
updated_at	string	ISO 8601 timestamp of when the project user was last updated
user	object	User object containing email, name, and timestamps
project	object	Project object containing project details

User Roles

Role	Permissions
owner	Full access. Can manage all aspects of the project, including billing and team members. Cannot be removed.
admin	Can manage monitors, incidents, integrations, and invite/remove team members (except owners).
collaborator	Can view and manage monitors and incidents. Cannot manage team members or integrations.

Invite User to Project

Invite a user to join the project with a specific role. The user will receive an invitation email if they don't already have an account.

http

POST /api/v1/projects/:project_uuid/project_users
Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X POST "https://app.uptinio.com/api/v1/projects/PRJ123456789/project_users" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_user": {
      "email": "newuser@example.com",
      "role": "admin"
    }
  }'

Path Parameters

Parameter	Type	Description
project_uuid	string	The UUID of the project

Request Body

json

{
  "project_user": {
    "email": "newuser@example.com",
    "role": "admin"
  }
}

Request Fields

Field	Type	Required	Description
email	string	Yes	Email address of the user to invite
role	string	Yes	Role to assign: `admin` or `collaborator` (cannot invite as `owner`)

Valid Roles

admin - Can manage monitors, incidents, integrations, and team members
collaborator - Can view and manage monitors and incidents

Note: You cannot invite users with the owner role. The owner role is automatically assigned to the project creator.

Response

Success (201 Created) - User already exists and was added:

json

{
  "id": 4,
  "role": "admin",
  "created_at": "2024-01-15T00:00:00Z",
  "updated_at": "2024-01-15T00:00:00Z",
  "user": {
    "email": "newuser@example.com",
    "name": "New User",
    "created_at": "2024-01-15T00:00:00Z",
    "updated_at": "2024-01-15T00:00:00Z"
  },
  "project": {
    "uuid": "PRJ123456789",
    "name": "My Team",
    "api_token": "abc123def456...",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "is_current": true
  }
}

Success (201 Created) - New user invited (invitation email sent):

json

{
  "message": "Invitation sent successfully",
  "email": "newuser@example.com",
  "role": "admin"
}

Error Responses:

400 Bad Request - Missing required fields:

json

{
  "error": "Email is required"
}

json

{
  "error": "Role is required"
}

403 Forbidden - User is not an admin or owner:

json

{
  "error": "You must be an admin or owner to perform this action"
}

422 Unprocessable Entity - Validation errors:

json

{
  "error": "Failed to invite user",
  "errors": [
    "User is already in the project",
    "Please choose a valid role"
  ]
}

422 Unprocessable Entity - Plan limit reached:

json

{
  "error": "Failed to invite user",
  "errors": [
    "You have reached the maximum number of team members for your plan. You can go to your billing page to upgrade your plan"
  ]
}

Remove User from Project

Remove a user from the project. Owners cannot be removed.

http

DELETE /api/v1/projects/:project_uuid/project_users/:id
Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN

Example with curl:

bash

curl -X DELETE "https://app.uptinio.com/api/v1/projects/PRJ123456789/project_users/3" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN" \
  -H "Content-Type: application/json"

Path Parameters

Parameter	Type	Description
project_uuid	string	The UUID of the project
id	integer	The ID of the project user relationship to remove

Response

Success (200 OK):

json

{
  "message": "User removed from project successfully"
}

Error Responses:

403 Forbidden - User is not an admin or owner:

json

{
  "error": "You must be an admin or owner to perform this action"
}

404 Not Found - Project user not found:

json

{
  "error": "Project user not found"
}

422 Unprocessable Entity - Cannot remove owner:

json

{
  "error": "Failed to remove user from project",
  "errors": [
    "Cannot remove the owner of the project."
  ]
}

Error Responses

All endpoints may return the following error responses:

401 Unauthorized - Missing or invalid authentication token:

json

{
  "error": "Unauthorized"
}

404 Not Found - Project not found:

json

{
  "error": "Project not found or you do not have access to it"
}

Permissions Summary

Action	Owner	Admin	Collaborator
List project users	✅	✅	✅
Invite users	✅	✅	❌
Remove users	✅	✅	❌
Remove owner	❌	❌	❌

Projects API - Manage projects and switch between them
Authentication Guide - Learn about authentication methods

Project Users API Reference ​

Authentication ​

List Project Users ​

Path Parameters ​

Response ​

Response Fields ​

User Roles ​

Invite User to Project ​

Path Parameters ​

Request Body ​

Request Fields ​

Valid Roles ​

Response ​

Remove User from Project ​

Path Parameters ​

Response ​

Error Responses ​

Permissions Summary ​

Related Endpoints ​

Project Users API Reference

Authentication

List Project Users

Path Parameters

Response

Response Fields

User Roles

Invite User to Project

Path Parameters

Request Body

Request Fields

Valid Roles

Response

Remove User from Project

Path Parameters

Response

Error Responses

Permissions Summary

Related Endpoints