Checkend

Management API

Programmatically manage your Checkend resources using API keys with scoped permissions.

API Keys vs Ingestion Keys

Checkend has two types of keys:

  • Ingestion Keys — App-specific keys for sending errors (see Authentication)
  • API Keys — System-wide keys with granular permissions for managing resources

This page documents the Management API, which uses API keys. For sending errors, use ingestion keys.

Overview

The Management API allows you to programmatically manage your Checkend resources including apps, problems, teams, users, and more. API keys are system-wide and offer granular permissions, enabling fine-grained control over what external applications can access and modify.

Authentication

All Management API requests must include the Checkend-API-Key header with a valid API key.

cURL 
curl -X GET https://your-checkend-instance.com/api/v1/apps \
  -H "Checkend-API-Key: your_api_key_here"
Status Description
401 Missing or invalid API key
403 API key is valid but lacks required permissions

Creating API Keys

API keys are created through the Checkend web interface. Navigate to API Keys in your dashboard to create a new key.

When creating an API key, you'll select which permissions it should have. The key value is only shown once during creation, so make sure to copy and store it securely.

Permissions

Permissions are defined using a resource:action pattern. When creating an API key, you select which permissions it should have.

Permission Description
apps:read List and view applications
apps:write Create, update, and delete applications
problems:read List and view problems
problems:write Resolve/unresolve problems and perform bulk operations
notices:read List and view individual notices
tags:read List tags associated with problems
tags:write Create and delete tags
teams:read List and view teams, members, and app assignments
teams:write Create, update, delete teams, and manage members/app assignments
users:read List and view user information
users:write Create, update, and delete users

Base URL

All Management API endpoints are prefixed with /api/v1/.

Example 
https://your-checkend-instance.com/api/v1/apps

Endpoints

Health Check

GET /api/v1/health

Checks the API's operational status. No authentication required.

Apps

GET /api/v1/apps List all applications
GET /api/v1/apps/:id Get application details
POST /api/v1/apps Create application
PATCH /api/v1/apps/:id Update application
DELETE /api/v1/apps/:id Delete application

Problems

GET /api/v1/apps/:app_id/problems List problems
GET /api/v1/apps/:app_id/problems/:id Get problem details
POST /api/v1/apps/:app_id/problems/:id/resolve Mark problem as resolved
POST /api/v1/apps/:app_id/problems/:id/unresolve Mark problem as unresolved
POST /api/v1/apps/:app_id/problems/bulk_resolve Bulk resolve problems

Notices

GET /api/v1/apps/:app_id/problems/:problem_id/notices List notices
GET /api/v1/apps/:app_id/problems/:problem_id/notices/:id Get notice details

Tags

GET /api/v1/apps/:app_id/problems/:problem_id/tags List tags
POST /api/v1/apps/:app_id/problems/:problem_id/tags Add tag to problem
DELETE /api/v1/apps/:app_id/problems/:problem_id/tags/:id Remove tag from problem

Teams

GET /api/v1/teams List teams
GET /api/v1/teams/:id Get team details
POST /api/v1/teams Create team
PATCH /api/v1/teams/:id Update team
DELETE /api/v1/teams/:id Delete team
GET /api/v1/teams/:team_id/members List team members
POST /api/v1/teams/:team_id/members Add team member
PATCH /api/v1/teams/:team_id/members/:id Update team member role
DELETE /api/v1/teams/:team_id/members/:id Remove team member

Users

GET /api/v1/users List users
GET /api/v1/users/:id Get user details
POST /api/v1/users Create user
PATCH /api/v1/users/:id Update user
DELETE /api/v1/users/:id Delete user

Example Requests

List Applications

cURL 
curl -X GET https://your-checkend-instance.com/api/v1/apps \
  -H "Checkend-API-Key: your_api_key_here"
Response 
[
  {
    "id": 1,
    "name": "My Rails App",
    "slug": "my-rails-app",
    "environment": "production",
    "notify_on_new_problem": true,
    "notify_on_reoccurrence": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "unresolved_problems_count": 5
  }
]

Create Application

cURL 
curl -X POST https://your-checkend-instance.com/api/v1/apps \
  -H "Content-Type: application/json" \
  -H "Checkend-API-Key: your_api_key_here" \
  -d '{
    "app": {
      "name": "New App",
      "environment": "production"
    }
  }'

Resolve Problem

cURL 
curl -X POST https://your-checkend-instance.com/api/v1/apps/my-app/problems/123/resolve \
  -H "Checkend-API-Key: your_api_key_here"

Create Team

cURL 
curl -X POST https://your-checkend-instance.com/api/v1/teams \
  -H "Content-Type: application/json" \
  -H "Checkend-API-Key: your_api_key_here" \
  -d '{
    "team": {
      "name": "Engineering Team",
      "owner_id": 1
    }
  }'

Error Responses

All error responses follow a consistent format:

Error Response 
{
  "error": "error_code",
  "message": "Human-readable error message"
}
Status Error Code Description
401 unauthorized Invalid or missing API key
403 forbidden API key lacks required permission
404 not_found Resource not found
422 validation_failed Validation error with details in messages array

Security Best Practices

  • Use minimal permissions — Only grant the permissions your integration actually needs
  • Store keys securely — Never commit API keys to version control. Use environment variables or secret management tools
  • Rotate keys regularly — Revoke and regenerate keys periodically or if you suspect they've been compromised
  • Monitor usage — Check the last_used_at timestamp in the API key dashboard to track activity
  • Use HTTPS — Always send requests over HTTPS in production

Revoked Keys

Revoked API keys will immediately stop working. Make sure to update any integrations using a revoked key before revoking it.