Uptinio Documentation

Appearance

Projects API Reference ​

This guide provides detailed information about the Projects API endpoints for managing projects and switching between them.

Authentication ​

All project endpoints require authentication using a User Authentication Token. Include your token in the Authorization header:

bash
Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN

For more information about authentication, see the Authentication Guide.

List Projects ​

Retrieve a list of all projects that the authenticated user has access to.

http
GET /api/v1/projects
Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN

Example with curl:

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

Response ​

json
[
  {
    "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
  },
  {
    "uuid": "PRJ987654321",
    "name": "Client Project",
    "api_token": "xyz789uvw012...",
    "created_at": "2024-01-15T00:00:00Z",
    "updated_at": "2024-01-15T00:00:00Z",
    "is_current": false
  }
]

Response Fields ​

FieldTypeDescription
uuidstringUnique identifier for the project
namestringProject name
api_tokenstringProject API token (for use with Project API Token authentication)
created_atstringISO 8601 timestamp of when the project was created
updated_atstringISO 8601 timestamp of when the project was last updated
is_currentbooleanWhether this is the user's currently active project

Switch Project ​

Switch the authenticated user's current project. This changes which project is used by default for subsequent API requests.

http
POST /api/v1/projects/:uuid/switch
Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN

Example with curl:

bash
curl -X POST "https://app.uptinio.com/api/v1/projects/PRJ987654321/switch" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN" \
  -H "Content-Type: application/json"

Path Parameters ​

ParameterTypeDescription
uuidstringThe UUID of the project to switch to

Response ​

Success (200 OK):

json
{
  "message": "Project switched successfully",
  "project": {
    "uuid": "PRJ987654321",
    "name": "Client Project",
    "api_token": "xyz789uvw012...",
    "created_at": "2024-01-15T00:00:00Z",
    "updated_at": "2024-01-15T00:00:00Z",
    "is_current": true
  }
}

Error Responses:

404 Not Found - Project not found or user doesn't have access:

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

403 Forbidden - User is not a member of the project:

json
{
  "error": "User is not a member of the project"
}

Using a Specific Project for a Request ​

You can use a specific project for a single API request without switching your current project. This is useful when you need to access resources from a different project temporarily.

Method 1: Query Parameter ​

Add project_uuid as a query parameter:

bash
curl -X GET "https://app.uptinio.com/api/v1/network_monitors?project_uuid=PRJ987654321" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN" \
  -H "Content-Type: application/json"

Method 2: Header ​

Add X-Project-UUID header:

bash
curl -X GET "https://app.uptinio.com/api/v1/network_monitors" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN" \
  -H "X-Project-UUID: PRJ987654321" \
  -H "Content-Type: application/json"

JavaScript Example:

javascript
const response = await fetch('https://app.uptinio.com/api/v1/network_monitors', {
  headers: {
    'Authorization': `Bearer ${authenticationToken}`,
    'X-Project-UUID': 'PRJ987654321',
    'Content-Type': 'application/json'
  }
});

Notes ​

  • The project must belong to the authenticated user
  • If the project UUID is invalid or the user doesn't have access, you'll receive a 404 error
  • This only affects the current request; it doesn't change your default current project
  • This works with any endpoint that uses authenticate_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"
}