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 a key from the same screen that created it; revocation takes effect immediately.

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.