API Keys

API keys are how external software identifies itself to WALDO. You generate a key in the dashboard, hand it to your integrator (or paste it into Claude / ChatGPT), and from that point forward they can read your analyses, trigger new ones, and manage your webhooks on your behalf — with no further input from you. Each key is yours alone, scoped to the permissions you choose, and revocable at any time.

TL;DR for CRE professionals: API keys turn WALDO into a back-end service for whatever tools you already use. Want a custom dashboard pulling live numbers from your latest analysis? Want Claude to "summarize the location quotient on my Cuyahoga County analysis"? Want to trigger a fresh analysis from a Slack slash command? You generate a key in Settings → API Keys, hand it to the integrator, and that's it.

What you get from this

• Plug WALDO into anything. Any tool that can make an HTTPS request — n8n, Zapier, Make, Pipedream, your custom CRM, Cursor, Claude Desktop, ChatGPT, a Slack app, a Retool dashboard — can read and write to WALDO with an API key.
• Granular permissions. A key issued to "the n8n flow that just emails reports" doesn't need permission to delete webhooks or run new analyses. You pick scopes per key.
• Audit trail. Every API call is logged with the key that made it, the route, the response, and the time. If something looks off, you can see exactly which integration is responsible.
• Revocable in one click. If a laptop walks off, if an integrator leaves, if Claude got a little too autonomous — revoke the key, and that channel is shut down immediately. The rest of your integrations keep working.

Common use cases

read:analyses

read:analyses

mcp:invoke

write:analyses

read:analyses

read:webhooks

write:webhooks

mcp:invoke

Step-by-step: creating your first API key

1. Sign in to WALDO as a Professional or Enterprise user. (API access isn't included on Basic — upgrade in Settings → Billing if needed.)
2. Go to Settings → API Keys in the left sidebar.
3. Click "New key." Give it a recognizable name (e.g. n8n production, Cursor MCP, Retool dashboard) so you'll remember what each key does.
4. Choose the scopes the key needs. Grant the minimum. A read-only key for a dashboard should not have
   text Copy

   write:analyses

   .
5. Click "Create key." The full key (
   text Copy

   waldo_live_...

   ) will be revealed — copy it now, it won't be shown again. (If you lose it, revoke it and create a new one.)
6. Paste the key into your integrator's environment variables (e.g.
   text Copy

   WALDO_API_KEY

   in
   text Copy

   .env

   , or directly into the secrets section of your automation tool). Never paste it into a public chat, GitHub, or a Loom video.

Available scopes

read:analyses

write:analyses

analysis.completed

read:webhooks

write:webhooks

mcp:invoke

You can combine multiple scopes on one key. Example: a single "n8n production" key with

read:analyses

write:analyses

read:webhooks

Key hygiene — the short version

• Treat keys like passwords. They grant access to your data and can run analyses on your behalf (which costs money under your plan).
• One key per integration. When you offboard an integration, you revoke just that one key. If five tools share one key and the laptop walks off, you have to rotate everything.
• Don't paste keys into chat / Slack / GitHub. Use environment variables, secrets managers (1Password, Doppler, Vault), or your platform's secrets UI.
• Rotate periodically. For long-lived integrations, plan to rotate the key every 6–12 months: create a new key, update the integration, revoke the old one.
• Watch the audit trail. If you see calls from a key you don't recognize, revoke it immediately.

Rate limits and quotas

WALDO enforces two layers of rate limiting:

• Short-window (per user, per minute) — protects against runaway loops and abuse. If your integrator gets a
  text Copy

  429 Too Many Requests

  , slow down.
• Monthly cost-units (per user, per billing period) — different endpoints cost different amounts (read endpoints = 1 unit, write endpoints = 50 units, MCP calls = 5 units). Quota varies by tier.

Check your current usage in Settings → Billing. If you're hitting quota, the upgrade prompt there shows the next tier up.

When something goes wrong

The most common API key issues:

• text Copy

  401 Unauthorized

  — The key is missing, mistyped, or revoked. Confirm the
  text Copy

  Authorization: Bearer waldo_live_...

  header is present and matches a non-revoked key.
• text Copy

  403 Forbidden

  — The key is valid but lacks the scope for the operation. Either add the scope to that key (you'll need to revoke + recreate — scopes aren't editable on existing keys) or use a different key.
• text Copy

  404 Not Found

  on a resource you own — The resource ID is wrong, or it belongs to a different user. WALDO returns 404 instead of 403 for cross-user access to avoid leaking ownership.
• text Copy

  429 Too Many Requests

  — You've hit the rate limit. Back off and retry; the response includes a
  text Copy

  Retry-After

  header.

Every API response includes an

X-Request-ID

For your integrator (or AI agent)

Everything below is the technical reference. Paste a link to this page into Claude / ChatGPT / Cursor and ask the AI to wire up the integration — it has all the information it needs.

Authentication

All calls to

/api/v1/*

text Copy
Authorization: Bearer waldo_live_<32-base64url-bytes>

Keys are looked up by SHA-256 hash. The full key value is shown to the user once at creation and never stored in plaintext on our side.

Server-to-server only. The public API does not set CORS headers — calling it from a browser would expose the key in client JavaScript. Keys belong on a server (or in an environment variable consumed by a server-side tool).

Key shape

text Copy
waldo_live_<32 base64url bytes, no padding>

Example:

waldo_live_3xY7pQ-cN8mZv4_HhKfWAa1bRsTu2EgD0iLoP9qVwXy

The dashboard displays

waldo_live_X…3xYz

Scopes (technical)

Scope strings (storage layer):

read:analyses

write:analyses

read:webhooks

write:webhooks

mcp:invoke

Stored on

api_keys.scopes TEXT[]

withApiAuth({ requireScopes: [...] })

/api/v1/*

withApiAuth({ requireScopes: ['read:analyses'] })

read:analyses

Tier gating (technical)

API access is paid-tier only. After key + scope check,

withApiAuth

subscription_tier

json Copy
{
  "type": "https://api.waldocre.io/errors/forbidden",
  "title": "API access requires a paid plan",
  "status": 403,
  "detail": "Upgrade to Professional or Enterprise to use the API.",
  "instance": "/api/v1/...",
  "request_id": "..."
}

Rate limits (technical)

Two layers:

1. Sliding-window per
   text Copy

   user_id

   (Upstash Redis): default 100 requests / 60 seconds. Tier-overridable.
2. Monthly cost-units per
   text Copy

   user_id

   (counted on
   text Copy

   api_audit_log.cost_units

   ): per-tier cap. Read = 1, write = 50, MCP = 5 per call.

Rate-limit responses are RFC 9457 problem-details with

429

Retry-After

Per-call audit log

Every authenticated call writes one row to

api_audit_log

text Copy
request_id, key_id, user_id, method, route, status, latency_ms, cost_units, ts

You can correlate any error response back to its row using the

X-Request-ID

Endpoint reference

All under

https://<your-waldo-host>/api/v1/

Analyses

/analyses

read:analyses

/analyses/:id

read:analyses

/analyses/:id/economic-base

read:analyses

/analyses/:id/employment/shift-share

read:analyses

/analyses/:id/market-metrics

read:analyses

/analyses/:id/supply

read:analyses

/analyses/:id/export?format=pdf|excel|pptx

read:analyses

/analyses/:id/status

read:analyses

/analyses

write:analyses

Idempotency-Key

202 Accepted

{ analysis_id, status_url }

Markets

/markets/search?q=...&type=county|msa

Webhooks

/webhooks

read:webhooks

/webhooks

write:webhooks

/webhooks/:id

read:webhooks

/webhooks/:id

write:webhooks

/webhooks/:id

write:webhooks

/webhooks/:id/rotate

write:webhooks

/webhooks/:id/deliveries

read:webhooks

/webhook-deliveries/:id/replay

write:webhooks

See the Webhooks docs for the full payload contract.

Idempotency

Write endpoints (currently

POST /v1/analyses

Idempotency-Key

text Copy
POST /api/v1/analyses
Authorization: Bearer waldo_live_...
Idempotency-Key: 3f9c-batch-march-cuyahoga
Content-Type: application/json

{ "market_code": "39035", "market_type": "county", ... }

Pagination

List endpoints use opaque cursor pagination:

text Copy
GET /api/v1/analyses?limit=50&cursor=eyJ1cGRhdGVkX2F0IjoiMjAyNi0w...

Cursors encode

(updated_at, id)

limit

next_cursor

null

Error format (RFC 9457)

json Copy
{
  "type": "https://api.waldocre.io/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "events must be a non-empty array",
  "instance": "/api/v1/webhooks",
  "request_id": "..."
}

request_id

X-Request-ID

MCP (Claude / Cursor / agents)

The

mcp:invoke

/api/mcp

Quickstart — Node.js

js Copy
const WALDO = 'https://app.waldocre.io/api/v1'

async function listAnalyses() {
  const res = await fetch(`${WALDO}/analyses?limit=20`, {
    headers: { Authorization: `Bearer ${process.env.WALDO_API_KEY}` },
  })
  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`)
  return res.json()
}

Quickstart — Python

python Copy
import os, requests

WALDO = "https://app.waldocre.io/api/v1"

def list_analyses():
    r = requests.get(
        f"{WALDO}/analyses",
        params={"limit": 20},
        headers={"Authorization": f"Bearer {os.environ['WALDO_API_KEY']}"},
    )
    r.raise_for_status()
    return r.json()

Quickstart — curl

bash Copy
curl -H "Authorization: Bearer $WALDO_API_KEY" \
     https://app.waldocre.io/api/v1/analyses?limit=20