How Brandop works, technically.
Data model, authentication, rate limits, errors and delivery rules.
How data is organized
Each workspace is one website with one domain. Pages, schema, jobs and scans belong to the workspace. An API key opens one workspace only.
- Workspace
- One site. Members have the role owner, admin or member.
- Page
- A URL path on the workspace domain, for example
/pricing. The fieldisSelectedForSchemadecides if the API serves schema for it. - Schema version
- Each generation saves a new JSON-LD version. When you edit the schema in the panel, the API serves your edit.
- Job
- Background work, for example
crawl_pageorgenerate_schema. The status ispending,processing,completed,failedorcancelled.
Authentication
Send the API key in the Authorization header with the Bearer scheme.
Authorization: Bearer YOUR_API_KEY- Keys start with
sk_and have 51 characters. - Brandop stores only a SHA-256 hash of the key. The full key shows once, when you create it.
- Owners and admins create and delete keys in Settings, then Integrations, then API Keys.
- A workspace can have up to 5 keys.
API access by plan
API access is a plan feature. The table shows the default plan settings.
| Plan | API access | Requests per minute |
|---|---|---|
| Starter | Yes | 60 |
| Pro | Not included | Not included |
| Agency | Yes | 1,000 |
| Enterprise | Yes | Set in your agreement |
The X-RateLimit-Limit header shows the limit for your workspace. Without API access, GET /schema answers 403 and the other endpoints answer 401.
Rate limits
The limit counts requests per workspace in a sliding window of one minute. All keys of a workspace share one counter.
| Header | Description |
|---|---|
X-RateLimit-Limit | Requests allowed per minute. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | Unix time in seconds when the oldest request leaves the window. |
When the workspace has no limit, X-RateLimit-Limit and X-RateLimit-Remaining are unlimited, and X-RateLimit-Reset is not sent.
Over the limit, the API answers 429 with the same headers. Wait until the reset time, then try again.
Errors
An error returns JSON with an error message. Some errors also have a code.
{
"error": "Page is not selected for schema delivery",
"code": "PAGE_NOT_SELECTED"
}| Status | When |
|---|---|
200 | Success. GET /schema returns schema: null when the page has no schema yet. |
201 | POST /pages created a page, or POST /schema/process created a job. |
400 | A required field is missing or has the wrong type, for example urlPath. |
401 | The Authorization header is missing or the key is not valid. Endpoints other than GET /schema also return 401 when the plan has no API access or the workspace is inactive. |
403 | GET /schema only. The code is API_ACCESS_NOT_IN_PLAN or WORKSPACE_INACTIVE (the plan ended or the payment grace period is over). |
404 | The page does not exist. GET /schema sends PAGE_NOT_FOUND, or PAGE_NOT_SELECTED when the page is not selected for delivery. |
409 | POST /pages: a page with this urlPath already exists. |
429 | The rate limit is exceeded. |
500 | Server error. Try again with backoff. |
Implementation guidelines
- Get schema on your server and put it in the HTML. AI crawlers that do not run JavaScript then see it.
- Forward the visitor's user agent in
X-Client-User-Agent. Brandop then records AI bot visits.X-Client-IPandX-Client-Signature-Agentare optional. - Brandop caches each schema for up to one hour. A new generation, an edit or a restore clears the cache. A deselected page stops at once.
- If you also cache on your side, keep it short. No webhook is sent when one page gets new schema.
- Retry
429and5xxresponses with exponential backoff. Do not repeat other4xxrequests without a change. - To keep schema current, turn on scheduled regeneration in Settings, then Automation. Each run crawls the pages again first. Scheduled regeneration is included in: Pro, Agency and Enterprise.
- When the monthly token budget is used up, new generation jobs are cancelled. The current schema stays live. Pages built from a ready template blueprint use no tokens and still update.