Guardian Logs API

Guardian Logs is a push-based log and error monitoring platform. You send events to us over HTTPS; we group them into issues, correlate them with deployments, and expose everything through a read API. Guardian Logs never needs inbound access to your servers.

This is the developer entry point. The machine-readable contract lives in openapi.yaml.

• Base API URL: https://guardianlogs.com/api/v1
• Health check: https://guardianlogs.com/api/health (public, no auth)
• Developer portal: <https://dev.guardianlogs.com> (renders from these docs)

Two credentials, two jobs

Guardian Logs has two separate credential systems. Neither can do the other's job — an ingest token cannot read data, and an API key cannot ingest. Both are sent as Authorization: Bearer <credential>.

Presenting the wrong credential type for an endpoint returns 401. See authentication.md and scopes.md.

Quick start

1. Create your credentials

An organization admin mints both in the app:

• Ingest token — Admin → Ingest credentials: pick an application + source

type, optionally label it, and copy the gl_live_… token. It is shown once.

• API key — Admin → API keys: select the read scopes you need

(apps:read, issues:read, …) and copy the gl_api_… key. Also shown once.

Export them so you never paste a real credential into a shell history or file:

export GUARDIAN_INGEST_TOKEN="gl_live_<publicId>_<secret>"   # write-only
export GUARDIAN_API_KEY="gl_api_<publicId>_<secret>"         # read-only

2. First request — health

No credential required:

curl "https://guardianlogs.com/api/health"

{ "ok": true, "db": true }

3. First log — ingest an event

curl -X POST "https://guardianlogs.com/api/v1/ingest" \
  -H "Authorization: Bearer $GUARDIAN_INGEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2026-09-13T16:22:11Z",
    "level": "error",
    "message": "Failed to process document",
    "errorClass": "TypeError",
    "environment": "production",
    "service": "web",
    "host": "app01",
    "deployment": "c8381ab",
    "route": "/api/process",
    "metadata": { "requestId": "abc123" }
  }'

{
  "ok": true,
  "batchId": "clw9k2xm0000abcd1234efgh",
  "received": 1,
  "accepted": 1,
  "duplicates": 0,
  "rejected": 0,
  "results": [ { "index": 0, "status": "accepted" } ]
}

Full ingest reference: ingest.md.

4. First read — list issues

curl "https://guardianlogs.com/api/v1/issues?limit=5" \
  -H "Authorization: Bearer $GUARDIAN_API_KEY"

{
  "data": [
    {
      "id": "clissue001abcd00000000",
      "title": "TypeError: cannot read properties of undefined",
      "status": "OPEN",
      "severity": "HIGH",
      "appId": "clapp0001kidscuts000000",
      "fingerprint": "7f3a9c2e1b",
      "eventCount": 42,
      "isRepeatOffender": true,
      "assignedToUserId": null,
      "firstSeenAt": "2026-09-10T08:14:00.000Z",
      "lastSeenAt": "2026-09-13T16:22:11.000Z"
    }
  ],
  "pagination": { "nextCursor": null }
}

Response format

Read endpoints return a JSON envelope:

{ "data": ... }                                 // single resource
{ "data": [ ... ], "pagination": { "nextCursor": "…" | null } }  // list

Errors always use:

{ "error": { "code": "…", "message": "…" } }

The ingest endpoint returns a per-event summary (202) rather than the data envelope — see ingest.md.

Pagination

List endpoints use opaque cursor pagination: ?limit= (1–100, default 50) and ?cursor=. Follow pagination.nextCursor until it is null. See pagination.md.

Rate limits

• Ingest: 600 events/min per token, 3000 events/min per org (counted in events).
• Read API: 120 requests/min per key, 600 requests/min per org.

Over budget → 429 with retryAfterSec and scope. See rate-limits.md.

Errors

Uniform envelope and stable status codes (400/401/403/404/413/429/500). 401 never reveals whether a credential, org, or resource exists. See errors.md.

Security

TLS only; redact secrets and PII at the source; one credential per host/source; rotate freely. See security.md.

Endpoint reference

All topics

• authentication.md — credentials, headers, failure modes
• scopes.md — read scopes and which endpoint needs which
• ingest.md — sending events (see also the concise ../api.md)
• apps.md · issues.md · signals.md · deployments.md
• pagination.md · rate-limits.md · errors.md
• idempotency.md · security.md