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 field isSelectedForSchema decides 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_page or generate_schema. The status is pending, processing, completed, failed or cancelled.

    Authentication

    Send the API key in the Authorization header with the Bearer scheme.

    HTTP
    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.
    Keep the key on your server. Do not put it in browser code or in a public repository.

    API access by plan

    API access is a plan feature. The table shows the default plan settings.

    PlanAPI accessRequests per minute
    StarterYes60
    ProNot includedNot included
    AgencyYes1,000
    EnterpriseYesSet 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.

    HeaderDescription
    X-RateLimit-LimitRequests allowed per minute.
    X-RateLimit-RemainingRequests left in the current window.
    X-RateLimit-ResetUnix 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.

    JSON
    {
      "error": "Page is not selected for schema delivery",
      "code": "PAGE_NOT_SELECTED"
    }
    StatusWhen
    200Success. GET /schema returns schema: null when the page has no schema yet.
    201POST /pages created a page, or POST /schema/process created a job.
    400A required field is missing or has the wrong type, for example urlPath.
    401The 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.
    403GET /schema only. The code is API_ACCESS_NOT_IN_PLAN or WORKSPACE_INACTIVE (the plan ended or the payment grace period is over).
    404The page does not exist. GET /schema sends PAGE_NOT_FOUND, or PAGE_NOT_SELECTED when the page is not selected for delivery.
    409POST /pages: a page with this urlPath already exists.
    429The rate limit is exceeded.
    500Server 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-IP and X-Client-Signature-Agent are 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 429 and 5xx responses with exponential backoff. Do not repeat other 4xx requests 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.