API overview

The EvoHub API lets scripts, CI jobs and other systems read and change what is in your organization: alerts, schedules, monitors, status pages and more. This page covers what every request has in common.

#Base URL

All endpoints live under one base URL:

https://evohub.io/api/v1

Every request must use HTTPS. Paths in these docs are relative to the base URL, so GET /monitors means GET https://evohub.io/api/v1/monitors.

#Authentication

Authenticate with an API key. Create one in the console under My Account → API Keys, or as an organization key under Organization → Organization Keys. See API keys and scopes.

Send the key in either of these headers. They are equivalent; use one.

curl https://evohub.io/api/v1/monitors \
  -H "Authorization: Bearer evohub_YOUR_KEY"

curl https://evohub.io/api/v1/monitors \
  -H "X-API-Key: evohub_YOUR_KEY"

• Every EvoHub API key starts with evohub_.
• A key works in exactly one organization, so you never pass an organization ID.
• If you send both headers, they must carry the same key, or the request is refused.
• A missing, unknown, revoked or expired key gets 401 Unauthorized. A valid key that lacks the scope for an endpoint gets 403 Forbidden. See Errors.

#A first request

List your organization's uptime monitors. The key needs the uptime:monitor:read scope.

curl https://evohub.io/api/v1/monitors \
  -H "Authorization: Bearer $EVOHUB_API_KEY"

{
  "data": [
    {
      "id": "…",
      "name": "Marketing site",
      "url": "https://www.acme.example",
      "type": "http",
      "interval_seconds": 60,
      "is_active": true,
      "last_status": "up",
      "last_checked_at": "2026-10-09T08:15:00Z",
      "created_at": "2026-09-01T10:00:00Z",
      "updated_at": "2026-10-01T12:30:00Z"
    }
  ]
}

The example shows a subset of the fields a monitor returns.

#Requests and responses

• Send request bodies as JSON with Content-Type: application/json.
• Successful responses are JSON with the result in a data field. Many endpoints also include "success": true.
• Errors are JSON with an error object instead. See Errors.
• Timestamps are RFC 3339 strings in UTC, for example 2026-10-09T08:15:00Z. Send timestamps in the same format.
• IDs are opaque strings. Store them as they are; do not parse them.

#Pagination

Most list endpoints return the whole list. Where a list can grow large, it is paged with limit and offset query parameters, and the response carries the total number of matches in meta.total next to data.

For example, the On-Call alert list returns 50 alerts by default. The key needs the oncall:alert:read scope.

curl "https://evohub.io/api/v1/alerts?status=triggered&limit=20&offset=0" \
  -H "Authorization: Bearer $EVOHUB_API_KEY"

{
  "data": [
    {
      "id": "…",
      "title": "High error rate on checkout",
      "severity": "critical",
      "status": "triggered",
      "created_at": "2026-10-09T08:01:12Z"
    }
  ],
  "success": true,
  "meta": { "total": 3 }
}

To read the next page, add limit to offset and request again until you have meta.total items.

#Request IDs

Every response carries an X-Request-ID header, and most error bodies repeat it as request_id. Include it when you contact support about a request; it lets us find exactly that call. You can also send your own X-Request-ID header, and EvoHub uses it instead of generating one.

#Rate limits

Requests are rate limited per API key (or, for requests without a key, per IP address), counted over a 10-second window. The limit is generous, on the order of 100 requests per second, and is meant to stop runaway scripts, not normal automation.

When you go over it, EvoHub answers 429 Too Many Requests with a RATE_LIMITED error and a Retry-After: 10 header. Wait at least that many seconds before retrying, and back off further if it happens again. Responses also carry X-RateLimit-Limit and X-RateLimit-Remaining headers.

Alert ingest URLs and heartbeat ping URLs are not subject to this limit, so a burst of alerts during an outage is never dropped for being too many.

#Related

• API keys and scopes
• Errors
• Roles and permissions