Skip to main content
Use REST API v1 to complete a typical rank-tracking workflow:
  1. Create a project.
  2. Add tracked keywords.
  3. Start a rank check.
  4. Retrieve ranking history.
This guide documents behavior shared across the HTTP API: base URLs, safe retries, response envelopes, pagination, and errors. Use the API Reference tab for the complete, resource-grouped endpoint inventory, request and response schemas, and interactive request builder. If you use an official client, start with the SDK docs for installation, language-level methods, and types. See Authentication and project selection for credential types and the PAT selector precedence contract. The REST API is served from:
Use the regional API root shown by your project. The EU hosted region currently uses:
Call the regional host directly instead of relying on a redirect from the marketing domain. Self-hosted:

​
Retry writes safely

All non-GET routes accept an idempotency key:
Reuse the same key only when retrying the same operation with the same authenticated credential, method, and path. A completed retry returns the original response and includes:
An operation still in progress returns 409 Conflict with Retry-After: 1. Completed responses remain replayable for 24 hours. With Valkey or another Redis-compatible configured, replay works across app instances and restarts.

​
Response shapes

List routes return:
Resource and mutation routes return the resource object directly. They are not wrapped in data. Discovery routes are mixed:

​
API version declarations

GET /capabilities advertises the API contracts the server serves in apiVersions. Clients may declare one of those values with Bisibility-API-Version: v1. The header is optional: an undeclared request continues through the same authentication, validation, and routing path used before version negotiation was added. An unsupported declared version returns 409 Conflict with problem type https://bisibility.com/problems/unsupported_api_version. See API errors for the response shape.

​
Pagination

List routes accept: The cursor is an opaque base64url value. Do not parse it in clients.

​
Errors

Errors use application/problem+json.
See API errors.

​
Integration workflows