Skip to content
9n9s Docs

REST API Reference

The 9n9s REST API provides programmatic access to manage all resources in your account, including organizations, projects, monitors, and users. All API access is over HTTPS and accessed from the https://api.9n9s.com domain. All data is sent and received as JSON.

Authentication

Section titled “Authentication”

Authentication is handled via API Keys. You can create and manage API keys from your Organization Settings > API Keys in the web UI.

You must include your API key in the Authorization header of every request:

Authorization: Bearer <your_api_key>

Rate Limiting

Section titled “Rate Limiting”

The API is rate-limited to prevent abuse. The rate limits are based on your account tier. If you exceed the rate limit, you will receive a 429 Too Many Requests response. Check the Retry-After header to see how many seconds to wait before making a new request.

Core Resources

Section titled “Core Resources”

The API is organized around RESTful resources. Here are the main endpoints:

Monitors

Section titled “Monitors”
  • GET /v1/monitors: List all monitors for the authenticated user’s organization.
  • POST /v1/monitors: Create a new monitor (Heartbeat or Uptime).
  • GET /v1/monitors/{monitorId}: Retrieve a single monitor.
  • PATCH /v1/monitors/{monitorId}: Update a monitor.
  • DELETE /v1/monitors/{monitorId}: Delete a monitor.

Projects

Section titled “Projects”
  • GET /v1/projects: List all projects.
  • POST /v1/projects: Create a new project.
  • GET /v1/projects/{projectId}: Retrieve a single project.
  • PATCH /v1/projects/{projectId}: Update a project.
  • DELETE /v1/projects/{projectId}: Delete a project.

Pulses (Heartbeat Monitors)

Section titled “Pulses (Heartbeat Monitors)”

While you can send pulses to the pulse.9n9s.com endpoints, you can also query the history of pulses via the main API.

  • GET /v1/monitors/{monitorId}/pulses: List the most recent pulses for a Heartbeat Monitor.

Checks (Uptime Monitors)

Section titled “Checks (Uptime Monitors)”
  • GET /v1/monitors/{monitorId}/checks: List the most recent checks for an Uptime Monitor.

Error Handling

Section titled “Error Handling”

The API uses conventional HTTP response codes to indicate the success or failure of an API request:

  • 200 - OK: The request was successful
  • 400 - Bad Request: The request was unacceptable, often due to missing a required parameter
  • 401 - Unauthorized: No valid API key provided
  • 403 - Forbidden: The API key doesn’t have permissions to perform the request
  • 404 - Not Found: The requested resource doesn’t exist
  • 429 - Too Many Requests: Too many requests hit the API too quickly
  • 500 - Server Error: Something went wrong on 9n9s’s end

Interactive API Documentation

Section titled “Interactive API Documentation”

For a complete, interactive API reference with request/response examples, visit our API Documentation Portal.