Projects

Project API keys are scoped to one project, so GET /projects returns only that project and POST /projects remains forbidden for them. A personal access token returns every project the user belongs to and can create a new one when its tier is at least write.

Create project

POST /api/v1/projects
Authorization: Bearer <personal_token>
Content-Type: application/json

{
  "name": "Example",
  "domain": "example.com",
  "tracking_scope": "country"
}

The response status is 201. Self-hosters may cap the number of projects owned by one user with BISIBILITY_MAX_PROJECTS_PER_USER.

List projects

GET /api/v1/projects
Authorization: Bearer <api_key>

Response:

{
  "data": [
    {
      "id": "prj_abc123",
      "name": "Example",
      "domain": "example.com",
      "created_at": "2026-06-28T10:00:00.000Z",
      "updated_at": "2026-06-28T10:00:00.000Z",
      "write_mode": "active"
    }
  ],
  "meta": { "next_cursor": null }
}

Get project

GET /api/v1/projects/{project_id}
Authorization: Bearer <api_key>

project_id can be the public prj_... id or the internal project id. It must match the authenticated API key’s project. Response:

{
  "id": "prj_abc123",
  "name": "Example",
  "domain": "example.com",
  "created_at": "2026-06-28T10:00:00.000Z",
  "updated_at": "2026-06-28T10:00:00.000Z",
  "write_mode": "active"
}

If the project does not match a project key, the API returns 403. A PAT gets 404 when the user is not a member, so project existence is not disclosed.

Update project

PATCH /api/v1/projects/{project_id}
Authorization: Bearer <api_key>
Content-Type: application/json

Request body may include name, domain, or both.

Get project defaults

GET /api/v1/projects/{project_id}/defaults
Authorization: Bearer <api_key>

Returns the effective market and schedule. Projects without a stored defaults row return the schema-defined schedule defaults and a market inferred from existing keywords, without creating a row. The source field is explicit, derived, or fallback and identifies how the effective market was selected.

Update project defaults

PATCH /api/v1/projects/{project_id}/defaults
Authorization: Bearer <api_key>
Content-Type: application/json

Project defaults store scheduling intent. country and device in this endpoint represent the project’s current default keyword market, derived from existing keywords. Supplying both country and device moves eligible keywords from the current default market to the new market. city narrows that market when it resolves inside the selected country. location_key is the canonical market selector and can point at a country, region, or city. Omitting market fields updates only the schedule and does not move keywords. country and device must be supplied together unless location_key is provided.

{
  "frequency": "weekly",
  "cron_expression": null,
  "timezone": "Europe/Warsaw",
  "jitter_minutes": 60,
  "country": "Poland",
  "city": "Warsaw",
  "location_key": "PL/Masovian Voivodeship/Warsaw",
  "device": "mobile"
}

Schedule-only update:

{
  "frequency": "daily",
  "timezone": "UTC",
  "jitter_minutes": 60
}

Response:

{
  "project_id": "prj_abc123",
  "frequency": "daily",
  "cron_expression": null,
  "timezone": "UTC",
  "jitter_minutes": 60,
  "serp_depth": 100,
  "serp_stop_on_match": true,
  "country": "United States",
  "city": null,
  "location_key": "US",
  "device": "desktop",
  "source": "explicit",
  "last_checked_at": null,
  "next_check_at": null,
  "updated_at": "2026-06-28T10:00:00.000Z"
}

Delete project

DELETE /api/v1/projects/{project_id}
Authorization: Bearer <api_key>

Deletes the scoped project and returns the deleted project resource. A PAT may delete it only when the user has the owner role.

Get started

Product guides

API reference

SDKs

AI / Agents

Create project

List projects

Get project

Update project

Get project defaults

Update project defaults

Delete project

​Create project

​List projects

​Get project

​Update project

​Get project defaults

​Update project defaults

​Delete project

Create project

List projects

Get project

Update project

Get project defaults

Update project defaults

Delete project