Programmatic setup

Create a programmatic key

NIGHTLAMP_TOKEN can be either your short-lived sign-in access token or a long-lived programmatic API key. Create an org-scoped key from Account → Workspace API keys when automation needs to manage every app in the workspace. Create an app-scoped key from App → Integrations → App API keys when the automation should only read and configure one app.

export NIGHTLAMP_TOKEN='nlk_org_…'

Keys are shown once and stored hashed. Revoke or rotate a key from the same screen that created it — revocation takes effect immediately, and rotating keeps the old key valid for a 24-hour overlap window so nothing breaks mid-swap.

Let your agent read its own error queue

The same NIGHTLAMP_TOKEN reads back the issues and incidents Nightlamp already caught for your app — no separate credential, no dashboard login. This is the piece that makes an agent-driven workflow (Cursor, Claude Code, a Replit agent, a cron job) able to close the loop on its own: catch a regression, poll it, fix it, watch it clear, without a human relaying the error by hand.

curl -H "Authorization: Bearer $NIGHTLAMP_TOKEN" \
  "https://api.nightlamp.app/v1/issues?status=unresolved&since=$LAST_POLL_ISO"

Every /v1 route is read-only, cursor-paginated (next_cursor / has_more), and scoped to exactly the org or app the key was issued for — an app-scoped key can never see a sibling app's issues, let alone another workspace's. Poll with since set to the ISO timestamp of your last successful read and the response only contains what changed.

• GET /v1/issues and GET /v1/issues/{id} — filterable by status, environment, severity.
• GET /v1/issues/{id}/events — the raw events behind an issue, for full context before an agent proposes a fix.
• GET /v1/incidents and GET /v1/incidents/{id} — monitor/probe-triggered alerts, same scoping and pagination.

Each issue returns id, status, severity, environment, title, source, fingerprint_slug, first_seen_iso/last_seen_iso, occurrence_count, tags, and — once closed — resolution_cause/resolution_note. Incidents return the equivalent alert-shaped fields: id, status, severity, title, source, occurred_at_iso, and resolved_at once closed. A full OpenAPI schema for /v1 is on the way; until then, the fields above are the complete public contract.

Start with the manifest

Request GET /apps/{app_id}/capabilities with a bearer token. The response is a machine-readable map of the control plane: monitor types, required fields, ingestion endpoints, webhook URLs, rotation paths, and status endpoints. Secrets are not returned; the manifest points to the endpoints that issue, rotate, or configure them. Email-dependent checks appear as the email_flow monitor type and require the org's AgentDraft QA mailbox to be enabled.

curl -H "Authorization: Bearer $NIGHTLAMP_TOKEN" \
  https://api.nightlamp.app/apps/$APP_ID/capabilities

Org-scoped AgentDraft setup

AgentDraft is configured once per workspace, not once per app. UI users connect it from an app's Integrations page; automation can read and update the same org-scoped connection through /orgs/me/integrations/agentdraft.

• GET reads connection status, masked key hint, alert toggle, and QA-mailbox toggle.
• POST validates and stores a key with mailbox:read and mailbox:write scopes.
• POST /test checks mailbox reachability, read scope, and quota when returned by AgentDraft.
• PATCH toggles alert delivery or the email-flow QA mailbox.
• DELETE disconnects AgentDraft and clears stored integration fields.

See AgentDraft and email-flow monitors for setup guidance and security details.

Configure monitors

Use the monitor_types array to select a supported check type, then create it with POST /apps/{app_id}/monitors. The same monitor can be patched, paused, resumed, or deleted through /monitors/{monitor_id}. For email-flow monitors, use ordered email_steps and one of the product presets for magic-link, OTP, or round-trip delivery.

curl -X POST "https://api.nightlamp.app/apps/$APP_ID/monitors" \
  -H "Authorization: Bearer $NIGHTLAMP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout API",
    "check_type": "api_canary",
    "interval_seconds": 300,
    "steps": [{
      "name": "health",
      "method": "GET",
      "url": "https://example.com/api/health",
      "expected_status_codes": [200],
      "request_timeout_seconds": 10
    }]
  }'

Webhook interfaces

The manifest lists every inbound webhook interface for the app: Sentry relay, legacy UptimeRobot, and GitHub release context. URL-path secrets and GitHub HMAC secrets are one-time values, so automation should call the listed rotation endpoint when it needs a fresh value.

curl -X POST "https://api.nightlamp.app/apps/$APP_ID/rotate-secret" \
  -H "Authorization: Bearer $NIGHTLAMP_TOKEN"

curl -X POST "https://api.nightlamp.app/apps/$APP_ID/rotate-github-secret" \
  -H "Authorization: Bearer $NIGHTLAMP_TOKEN"

Monitor the monitors

Programmatic setup should end with readback. Use /apps/{app_id}/ingest-status to confirm recent SDK, relay, Kubernetes log, or CloudWatch traffic. Use /monitors/{monitor_id}/history and /monitors/{monitor_id}/uptime to confirm probes are running and producing aggregates.

curl -H "Authorization: Bearer $NIGHTLAMP_TOKEN" \
  https://api.nightlamp.app/apps/$APP_ID/ingest-status

Recommended automation flow

1. Discover

   Fetch the capabilities manifest and cache it with the app id.

2. Apply

   Create or patch monitors, rotate one-time secrets only when needed, and configure external webhook senders.

3. Verify

   Read ingest status, monitor history, uptime aggregates, and recent releases before your CI job exits green.

For exact request and response schemas, open the API reference.

Common questions about programmatic setup

How do I create a programmatic API key for Nightlamp?

Mint an org-scoped programmatic key from the dashboard, store it as a secret in your automation environment, and send it as a bearer token on every request. Rotate the one-time secret only when it is exposed or on your normal rotation schedule.

How do I create and update monitors from code?

Fetch the capabilities manifest, then create or patch monitors against the app id. The same request shape configures UI, API-driven, and AgentDraft-backed email-flow monitors, so one automation flow covers every monitor type.

How do I verify a programmatic setup succeeded before CI exits?

Read ingest status, monitor history, uptime aggregates, and recent releases after applying changes. Gate your CI job on those reads so a green build means the monitors are actually receiving data, not just that the API accepted the request.

Can an AI coding agent read its own errors from Nightlamp?

Yes. GET /v1/issues and GET /v1/incidents let any app's NIGHTLAMP_TOKEN poll its own unresolved issues and open incidents — the same read-only, cursor-paginated API a cron job or an agent loop (Cursor, Claude Code, a Replit agent) can call directly, so it can catch a regression, investigate with /v1/issues/{id}/events, and fix it without a human relaying the error by hand.