Quickstart
Create a key in the dashboard, then call feed endpoints with a bearer token. Every feed payload includes sources, fetched_at, licence, attribution, and the disclaimer. The base URL is https://data.wearedeepworks.com.
curl -s https://data.wearedeepworks.com/v1/feeds/nhc-storms/sample curl -s https://data.wearedeepworks.com/v1/feeds \ -H "Authorization: Bearer $DEEP_DATA_KEY" curl -s https://data.wearedeepworks.com/v1/feeds/nhc-storms \ -H "Authorization: Bearer $DEEP_DATA_KEY" curl -s https://data.wearedeepworks.com/v1/status
The sample does not need a key. It returns the latest stored NHC envelope, or a committed fixture with fetched_at null when no snapshot is available.
Send Authorization: Bearer dd_live_…. Keys are shown once in the dashboard and stored as a SHA-256 digest. Missing or unknown keys return 401 with error.code unauthorized.
Free is 10 requests per minute and 100 per day, with no credit debit inside that quota. Starter is 60 per minute. Pro is 300 per minute. Over the limit returns 429 rate_limited. Starter and Pro also need a credit or the call returns 402 payment_required. Billing opens soon, so new accounts stay on the free quota.
| 304 | Not modified. No body and no credit debit. The call still counts toward the per-key rate limit. |
|---|---|
| 400 invalid_query | limit, cursor, omit, or feed was not valid. This does not count toward the quota. |
| 401 unauthorized | No bearer token, or the key was not recognized. |
| 402 payment_required | Paid plan with no credits left. |
| 404 not_found | Unknown feed, or a sample slug other than nhc-storms. |
| 429 rate_limited | Minute or daily cap for the plan. |
| 503 database_unavailable | The database could not be reached. |
Error bodies use { "error": { "code", "message" } }.
Feed reads send ETag and Cache-Control: private, max-age=15. Send the ETag back as If-None-Match. A 304 has an empty body and does not debit a credit. It still counts toward the per-key minute and day caps, because the key was checked.
GET /v1/status, the NHC sample, OpenAPI, and llms.txt are public caches. Status accepts ?feed=nhc-storms when you only need one row. A feed list does not include record payloads.
omit=data on a feed or its history returns the envelope without the JSON payload. On a single feed, has_record says whether a row is stored.
History defaults to 30 changes and reports default to 10. Usage defaults to 50. limit can be from 1 to 100. The body includes page.next_cursor, and history sends a Link header with rel=next when another page exists. Pass cursor back unchanged. GET /v1/usage is not metered.
| GET /v1/feeds | Catalog with provenance. Metered. |
|---|---|
| GET /v1/feeds/{slug} | Latest record. Metered. |
| GET /v1/feeds/nhc-storms/sample | Public sample. Not metered. |
| GET /v1/feeds/{slug}/history | Change page. limit, cursor, and omit=data. Metered. |
| GET /v1/feeds/{slug}/charts | Chart series. Metered. |
| GET /v1/feeds/{slug}/reports | Ingest reports. Metered. |
| GET /v1/status | Public feed status. Not metered. |
| GET /v1/openapi | OpenAPI document. Not metered. |
| POST /v1/billing/checkout | Billing opens soon. |
| POST /v1/billing/portal | Billing opens soon. |
| /mcp | Returns 501. MCP is not available yet. |
ok is a successful ingest inside the stale window. degraded means the upstream refused the fetch, currently ECCB HTTP 403, and no rates were stored. pending means the feed is enabled and has not completed a fetch yet. not_enabled means the slug is seeded only. stale means the last success is older than the feed's stale window. error means the worker recorded a failed fetch.
Informational only — not financial, legal, or safety advice. Verify with the cited source.