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¶

Overview¶

Authentication¶

Project Object Schema¶

Project Model¶

Field Descriptions¶

Validation Rules¶

Endpoints¶

List All Projects¶

Create Project¶

Get Project Details¶

Update Project (Full Update)¶

Update Project (Partial Update)¶

Delete Project¶

Get Project Services¶

Assign Services to Project¶

Unassign Services from Project¶

Reorder Projects¶

Common Use Cases¶

Creating a Project with Color Coding¶

Bulk Service Assignment¶

Moving Services Between Projects¶

Reorganizing Project Order¶

Error Codes¶

Best Practices¶

Naming Conventions¶

Color Schemes¶

Project Organization¶

Related Resources¶

Changelog¶

v1.0 (Current)¶