The Projects API provides endpoints for organizing monitoring services into logical groups.

Projects API

The Projects API provides endpoints for organizing monitoring services into logical groups. Projects help categorize services by environment, customer, application, or any criteria relevant to your use case.

Overview

Projects serve as organizational containers for services, allowing you to:

Group related services together
Apply visual categorization with colors and icons
Maintain ordered project lists
Bulk manage service assignments
Track service counts per project

Authentication

All Projects API endpoints require JWT authentication. Include your access token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

See the Authentication Guide for details on obtaining tokens.

Project Object Schema

Project Model

{
  "id": 1,
  "name": "Production Services",
  "description": "All production environment monitoring services",
  "color": "#EF4444",
  "icon": "server",
  "order": 0,
  "service_count": 12,
  "date_created": "2024-01-15T10:30:00Z",
  "date_modified": "2024-01-20T14:45:00Z"
}

Field Descriptions

Field	Type	Required	Description
`id`	integer	Read-only	Unique identifier for the project
`name`	string	Yes	Project name (max 128 characters, unique per user)
`description`	string	No	Detailed description (max 500 characters)
`color`	string	No	Hex color code for visual identification (default: `#3B82F6`)
`icon`	string	No	Icon identifier for visual representation (max 64 characters)
`order`	integer	No	Display order (default: 0)
`service_count`	integer	Read-only	Count of services assigned to this project
`date_created`	datetime	Read-only	Project creation timestamp (ISO 8601)
`date_modified`	datetime	Read-only	Last modification timestamp (ISO 8601)

Validation Rules

Name:

Required field
Maximum 128 characters
Must be unique within user's account
Cannot be empty or whitespace only

Description:

Optional field
Maximum 500 characters

Color:

Optional field
Must be valid hex color format: #RRGGBB (6 hex digits)
Case-insensitive (will be normalized to uppercase)
Example: #FF5733, #3B82F6

Icon:

Optional field
Maximum 64 characters
No format validation (any string accepted)

Order:

Optional field
Integer value
Used for sorting projects in dashboard
Lower values appear first

Endpoints

List All Projects

Retrieve all projects for the authenticated user.

Endpoint: GET /api/v1/projects

Authentication: Required

Query Parameters: None

Request Example:

curl -X GET https://app.uptimehunt.io/api/v1/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response: 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "Production",
      "description": "Production environment services",
      "color": "#EF4444",
      "icon": "server",
      "order": 0,
      "service_count": 12,
      "date_created": "2024-01-15T10:30:00Z",
      "date_modified": "2024-01-20T14:45:00Z"
    },
    {
      "id": 2,
      "name": "Staging",
      "description": "Staging environment for testing",
      "color": "#F59E0B",
      "icon": "test-tube",
      "order": 1,
      "service_count": 8,
      "date_created": "2024-01-15T10:35:00Z",
      "date_modified": "2024-01-18T09:20:00Z"
    }
  ]
}

Response Fields:

data: Array of project objects ordered by order field, then by name

Create Project

Create a new project for organizing services.

Endpoint: POST /api/v1/projects

Authentication: Required

Request Body:

{
  "name": "Production Services",
  "description": "All production environment monitoring",
  "color": "#EF4444",
  "icon": "server",
  "order": 0
}

Request Example:

curl -X POST https://app.uptimehunt.io/api/v1/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Services",
    "description": "All production environment monitoring",
    "color": "#EF4444",
    "icon": "server",
    "order": 0
  }'

Response: 201 Created

{
  "data": {
    "id": 3,
    "name": "Production Services",
    "description": "All production environment monitoring",
    "color": "#EF4444",
    "icon": "server",
    "order": 0,
    "service_count": 0,
    "date_created": "2024-01-25T15:22:00Z",
    "date_modified": "2024-01-25T15:22:00Z"
  }
}

Error Responses:

400 Bad Request - Validation error:

{
  "error": {
    "message": "Validation failed",
    "details": {
      "name": ["A project with this name already exists"]
    }
  }
}

400 Bad Request - Invalid color format:

{
  "error": {
    "message": "Validation failed",
    "details": {
      "color": ["Color must be in hex format (e.g., #3B82F6)"]
    }
  }
}

Get Project Details

Retrieve a specific project by ID.

Endpoint: GET /api/v1/projects/{id}

Authentication: Required

Path Parameters:

id (integer): Project ID

Request Example:

curl -X GET https://app.uptimehunt.io/api/v1/projects/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response: 200 OK

{
  "data": {
    "id": 1,
    "name": "Production",
    "description": "Production environment services",
    "color": "#EF4444",
    "icon": "server",
    "order": 0,
    "service_count": 12,
    "date_created": "2024-01-15T10:30:00Z",
    "date_modified": "2024-01-20T14:45:00Z"
  }
}

Error Responses:

404 Not Found:

{
  "error": {
    "message": "Not found."
  }
}

Update Project (Full Update)

Replace all project fields with new values.

Endpoint: PUT /api/v1/projects/{id}

Authentication: Required

Path Parameters:

id (integer): Project ID

Request Body (all fields required):

{
  "name": "Production Environment",
  "description": "Updated production services",
  "color": "#DC2626",
  "icon": "server-stack",
  "order": 0
}

Request Example:

curl -X PUT https://app.uptimehunt.io/api/v1/projects/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Environment",
    "description": "Updated production services",
    "color": "#DC2626",
    "icon": "server-stack",
    "order": 0
  }'

Response: 200 OK

{
  "data": {
    "id": 1,
    "name": "Production Environment",
    "description": "Updated production services",
    "color": "#DC2626",
    "icon": "server-stack",
    "order": 0,
    "service_count": 12,
    "date_created": "2024-01-15T10:30:00Z",
    "date_modified": "2024-01-25T16:45:00Z"
  }
}

Error Responses:

404 Not Found - Project doesn't exist or not owned by user

400 Bad Request - Validation error (see Create Project errors)

Update Project (Partial Update)

Update specific project fields without replacing all values.

Endpoint: PATCH /api/v1/projects/{id}

Authentication: Required

Path Parameters:

id (integer): Project ID

Request Body (only include fields to update):

{
  "color": "#10B981",
  "description": "Updated description only"
}

Request Example:

curl -X PATCH https://app.uptimehunt.io/api/v1/projects/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "color": "#10B981",
    "description": "Updated description only"
  }'

Response: 200 OK

{
  "data": {
    "id": 1,
    "name": "Production",
    "description": "Updated description only",
    "color": "#10B981",
    "icon": "server",
    "order": 0,
    "service_count": 12,
    "date_created": "2024-01-15T10:30:00Z",
    "date_modified": "2024-01-25T17:00:00Z"
  }
}

Error Responses: Same as PUT endpoint

Delete Project

Delete a project. Services assigned to this project will be unassigned (moved to "Unassigned" category).

Endpoint: DELETE /api/v1/projects/{id}

Authentication: Required

Path Parameters:

id (integer): Project ID

Request Example:

curl -X DELETE https://app.uptimehunt.io/api/v1/projects/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response: 204 No Content

No response body returned on successful deletion.

Error Responses:

404 Not Found:

{
  "error": {
    "message": "Not found."
  }
}

Service Reassignment

When a project is deleted, all services assigned to it are automatically unassigned (project field set to null). The services themselves are NOT deleted.

Get Project Services

Retrieve all services assigned to a specific project.

Endpoint: GET /api/v1/projects/{id}/services

Authentication: Required

Path Parameters:

id (integer): Project ID

Request Example:

curl -X GET https://app.uptimehunt.io/api/v1/projects/1/services \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response: 200 OK

{
  "data": [
    {
      "id": 5,
      "name": "Main Website",
      "type": "http",
      "enabled": true,
      "interval": 3,
      "config": {
        "url": "https://example.com",
        "method": "GET"
      },
      "project_id": 1,
      "project": {
        "id": 1,
        "name": "Production",
        "color": "#EF4444",
        "icon": "server"
      },
      "date_created": "2024-01-16T08:15:00Z",
      "date_modified": "2024-01-20T10:30:00Z"
    }
  ]
}

Assign Services to Project

Assign one or more services to a project.

Endpoint: POST /api/v1/projects/{id}/assign_services

Authentication: Required

Path Parameters:

id (integer): Project ID

Request Body:

{
  "service_ids": [5, 7, 12]
}

Request Example:

curl -X POST https://app.uptimehunt.io/api/v1/projects/1/assign_services \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "service_ids": [5, 7, 12]
  }'

Response: 200 OK

{
  "message": "Successfully assigned 3 services to project"
}

Error Responses:

400 Bad Request - Service not found or not owned:

{
  "error": "Some services not found or not owned by you"
}

404 Not Found - Project not found

Unassign Services from Project

Remove service assignments from a project (services move to "Unassigned").

Endpoint: DELETE /api/v1/projects/{id}/unassign_services

Authentication: Required

Path Parameters:

id (integer): Project ID

Request Body:

{
  "service_ids": [5, 7]
}

Request Example:

curl -X DELETE https://app.uptimehunt.io/api/v1/projects/1/unassign_services \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "service_ids": [5, 7]
  }'

Response: 200 OK

{
  "message": "Successfully unassigned 2 services from project"
}

Notes:

Only services that belong to this project and are owned by the user will be unassigned
Services not found or not in this project are silently ignored
Unassigned services have their project field set to null

Reorder Projects

Update the display order of multiple projects at once.

Endpoint: PUT /api/v1/projects/reorder

Authentication: Required

Request Body:

{
  "projects": [
    {"id": 1, "order": 0},
    {"id": 3, "order": 1},
    {"id": 2, "order": 2}
  ]
}

Request Example:

curl -X PUT https://app.uptimehunt.io/api/v1/projects/reorder \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "projects": [
      {"id": 1, "order": 0},
      {"id": 3, "order": 1},
      {"id": 2, "order": 2}
    ]
  }'

Response: 200 OK

{
  "message": "Successfully reordered projects"
}

Notes:

Only updates projects that exist and are owned by the user
Projects not included in the request maintain their current order
Invalid project IDs are silently ignored

Common Use Cases

Creating a Project with Color Coding

Environment-based projects with color coding:

# Production (Red)
curl -X POST https://app.uptimehunt.io/api/v1/projects \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "description": "Production environment services",
    "color": "#EF4444",
    "icon": "server",
    "order": 0
  }'

# Staging (Yellow)
curl -X POST https://app.uptimehunt.io/api/v1/projects \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging",
    "description": "Staging environment",
    "color": "#F59E0B",
    "icon": "test-tube",
    "order": 1
  }'

# Development (Green)
curl -X POST https://app.uptimehunt.io/api/v1/projects \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development",
    "description": "Development environment",
    "color": "#10B981",
    "icon": "code",
    "order": 2
  }'

Bulk Service Assignment

Assign multiple services to a project:

# Get all services to find IDs
curl -X GET https://app.uptimehunt.io/api/v1/services \
  -H "Authorization: Bearer <token>"

# Assign services 1, 3, 5, 7 to project 1
curl -X POST https://app.uptimehunt.io/api/v1/projects/1/assign_services \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "service_ids": [1, 3, 5, 7]
  }'

Moving Services Between Projects

Move services from one project to another:

# First, get services from old project
curl -X GET https://app.uptimehunt.io/api/v1/projects/1/services \
  -H "Authorization: Bearer <token>"

# Unassign from old project
curl -X DELETE https://app.uptimehunt.io/api/v1/projects/1/unassign_services \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"service_ids": [5, 7]}'

# Assign to new project
curl -X POST https://app.uptimehunt.io/api/v1/projects/2/assign_services \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"service_ids": [5, 7]}'

Alternatively, update services directly (see Services API):

# Update service project directly
curl -X PATCH https://app.uptimehunt.io/api/v1/services/5 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"project_id": 2}'

Reorganizing Project Order

Reorder projects for custom display:

curl -X PUT https://app.uptimehunt.io/api/v1/projects/reorder \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "projects": [
      {"id": 3, "order": 0},
      {"id": 1, "order": 1},
      {"id": 2, "order": 2},
      {"id": 4, "order": 3}
    ]
  }'

Error Codes

HTTP Status	Error Code	Description
400	`VALIDATION_ERROR`	Request validation failed
401	`UNAUTHORIZED`	Missing or invalid authentication token
404	`NOT_FOUND`	Project not found or not owned by user
500	`INTERNAL_ERROR`	Server error

Best Practices

Naming Conventions

Use clear, consistent naming:

Environment-Based:

Production, Staging, Development, QA

Customer-Based:

Acme Corp, Beta Customer, Internal Services

Application-Based:

Website, Mobile API, Admin Dashboard

Color Schemes

Recommended color coding:

By Environment:

Production:  #EF4444 (Red)
Staging:     #F59E0B (Yellow)
Development: #10B981 (Green)
QA/Testing:  #3B82F6 (Blue)

By Priority:

Critical:    #DC2626 (Dark Red)
Important:   #EA580C (Orange)
Standard:    #3B82F6 (Blue)
Low:         #6B7280 (Gray)

Project Organization

Small Teams (1-10 services):

Use environment-based projects (Production, Staging, Dev)
Keep it simple with 2-4 projects maximum

Medium Teams (10-50 services):

Combine environment + application
Examples: "Production Web", "Production API", "Staging All"

Large Teams (50+ services):

Use hierarchical naming (no nesting, but naming convention)
Examples: "Prod-Customer-A", "Prod-Customer-B", "Prod-Internal"

Service Providers:

One project per customer/client
Use consistent color coding for quick identification
Include customer name in project name

Services API - Managing monitoring services
Authentication Guide - API authentication
User Guide: Projects - Frontend usage guide
Getting Started - Creating your first service

Changelog

v1.0 (Current)

Initial release
Basic CRUD operations
Service assignment/unassignment
Project reordering
Color and icon support

Projects API

On this page