Data API
Read a content snapshot. Reports record ids for the next rebuild. Snapshots do not.
Last updated on
The public base URL is https://api.databob.dev. The same routes are Convex HTTP actions on the deployment site URL. Ingest stays on the Worker. A hit returns the stored snapshot. It does not query Analytics Engine.
info.version is 1. Every path is under /v1. A breaking change gets a new path prefix. Adding an optional JSON field is not a breaking change. Ignore unknown fields. Branch on error, not on message.
Two routes, one report
GET /v1/reports/content reads the snapshot and records each content id so the daily rebuild will refresh it. GET /v1/snapshots/content reads the same snapshot and does not record a request. There are no other report types.
Query
| Parameter | Required | Values |
|---|---|---|
period | yes | 7d or 28d |
content_id | one of the two id parameters | A single content id. Do not combine with content_ids. |
content_ids | one of the two id parameters | Comma-separated. At most 20. |
project_id | when the key can read every site | A project id. A key limited to one site uses that site when this is omitted. |
A different site in the same org is 403. A missing project and a project in another org are both 404.
The script tag stores the pathname as the content id. Query with that path, for example /pricing, unless a collect body included content_id. The samples below use post_123, which is the id in the OpenAPI examples.
Samples
curl -sS \
-H "Authorization: Bearer dbk_live_REPLACE" \
"https://api.databob.dev/v1/reports/content?project_id=PROJECT_ID&period=7d&content_id=post_123"curl -sS \
-H "Authorization: Bearer dbk_test_REPLACE" \
"https://api.databob.dev/v1/snapshots/content?project_id=PROJECT_ID&period=28d&content_ids=post_123,post_456"Response
{
"report": "content",
"period": "7d",
"items": [
{
"id": "post_123",
"views": 40,
"previous_views": 12,
"enough_data": true
}
]
}views is the current window. previous_views is the window before it. enough_data is false when the current window was extrapolated from fewer than three unweighted rows. If no snapshot exists yet, the item is views: 0, previous_views: 0, enough_data: false. A batch larger than 20 is rejected. At most 20 items are returned.
The rebuild runs daily at 04:00 UTC. Calling the reports route records the ids for that job. Calling the snapshots route does not.
The interactive reference, with the auth header, code samples, and error bodies, is generated from the OpenAPI document:
SDKs are coming later
Generated clients are not published. The OpenAPI document is the contract they will follow. Ignore unknown JSON fields, and branch on error.