Instance import

Instance import accepts an export package and restores keywords plus optional rank history into the project associated with a migration token. Use the single request endpoint for small packages and the session protocol for large packages. These versioned paths are included in /api/v1/openapi.json.

Endpoints

POST /api/v1/cloud/import
GET  /api/v1/cloud/import/compatibility
POST /api/v1/cloud/import/sessions
PUT  /api/v1/cloud/import/sessions/{sessionId}/chunks/{index}
POST /api/v1/cloud/import/sessions/{sessionId}/finalize

Authentication

Instance import uses a migration token, not a bsb_key_live_... API key. Every import endpoint requires Bearer authentication:

Authorization: Bearer mig_...

Invalid, expired, or already-used tokens return 419 with an unauthorized problem response. Missing or malformed tokens return 401. All import request objects reject unknown fields. Public IDs and checksums must use their exact lowercase representation without surrounding whitespace. Numbers and booleans must use native JSON types rather than strings.

Migration Tokens

A migration token is bound to one project by design: it authorizes importing into exactly the project it was minted for, is single use, and expires after BISIBILITY_MIGRATION_TOKEN_TTL_MINUTES. This is what lets the exporting side push data into a destination project without ever holding that project’s API key. There is no instance-global token; a broader credential would grant more than an import needs. Tokens are minted and managed through the ordinary project-scoped REST API using an Authorization: Bearer <api_key> key for the destination project:

Method	Path	Purpose
`GET`	`/api/v1/projects/{project_id}/migration-tokens`	List migration tokens without exposing raw secrets.
`POST`	`/api/v1/projects/{project_id}/migration-tokens`	Mint a `full` or `keywords` migration token.
`DELETE`	`/api/v1/projects/{project_id}/migration-tokens/{token_id}`	Revoke through the project-scoped route.
`DELETE`	`/api/v1/migration-tokens/{token_id}`	Revoke through the short route.

The raw mig_... value is returned only when minted. Tokens can also be minted from the in-app wizard. Migration-token identifiers are strict ferry_ v3 public IDs; import jobs and session identifiers are strict imp_ v3 public IDs.

Compatibility Preflight

Call the public compatibility endpoint before generating an export:

GET /api/v1/cloud/import/compatibility

Response:

{
  "schema_versions_supported": [7, 6],
  "app_version": "0.2.0",
  "latest_migration": "20260730204200_rank_check_normalization_version"
}

The endpoint is anonymous and rate limited. latest_migration is null when the migration table cannot be read.

Single Request Import

Post the export package directly to /api/v1/cloud/import:

{
  "exported_at": "2026-06-28T10:00:00.000Z",
  "version": 7,
  "project_id": "prj_abcdefghijklmnopqrstuvwx",
  "scope": "history",
  "keywords": [
    {
      "id": "kw_abcdefghijklmnopqrstuvwx",
      "keyword": "rank tracker api",
      "location": "United States",
      "location_key": "US",
      "device": "desktop",
      "target_url": "https://example.com/rank-tracker",
      "tags": ["api"],
      "rankingHistory": [
        {
          "checkedAt": "2026-06-20T10:00:00.000Z",
          "normalizationVersion": "v1",
          "position": 3,
          "previousPosition": 4,
          "provider": "dataforseo",
          "rankingUrl": "https://example.com/rank-tracker",
          "requestedDepth": 100
        }
      ]
    }
  ],
  "alert_rules": [],
  "competitors": [],
  "notification_preferences": [],
  "saved_views": []
}

The endpoint accepts strict v7 packages and compatible v6 packages. Version 7 exports identify every keyword location with location_key; the human-readable location label can name a country, region, or city. Version 6 continues to use the legacy country label. All versions accept only snake-case package fields, exact lowercase public IDs, and native JSON number and boolean types. They reject wrapper objects, body tokens, and unknown fields. A version 5 package is accepted only when every rankingHistory array is empty; update and re-export any version 5 package that carries ranking history. Top-level fields:

Field	Description
`keywords`	Required. Up to 500 keyword records.
`exported_at`	Optional ISO-8601 timestamp.
`project_id`	Required strict `prj_` v3 source project ID.
`scope`	Optional. `current` or `history`.
`alert_rules`	Required alert-rule records.
`competitors`	Required competitor records.
`notification_preferences`	Required notification preference records.
`saved_views`	Required saved-view records.

Keyword fields:

Field	Description
`id`	Required strict `kw_` v3 source keyword ID.
`keyword`	Required keyword text.
`device`	Required: `desktop` or `mobile`.
`location`	Required human-readable source location label.
`location_key`	Required in version 7. Canonical country, region, or city key, optionally qualified with `@language`. It takes precedence over `location`.
`target_url`	Absolute URL, path, `null`, or omitted.
`tags`	Up to 12 tags. Defaults to `[]`.
`rankingHistory`	Optional. Up to 5000 historical checks per keyword.

Each competitor record requires its source cmp_ public ID and canonical domain. The destination still matches and upserts competitors by domain. History fields:

Field	Description
`checkedAt`	Required ISO-8601 timestamp.
`normalizationVersion`	Required normalization contract version, currently `v1`.
`position`	Required integer position or `null`.
`previousPosition`	Required integer previous position or `null`.
`provider`	Required provider identifier captured by the source check.
`rankingUrl`	Required absolute URL, path, or `null`.
`requestedDepth`	Required requested SERP depth (`10`, `20`, `50`, `100`, or `null`). `null` rows are imported and shown in ranking history. Visibility requires a known requested depth of at least 20. Checks with unknown depth do not update Visibility. Affected keywords still count toward its coverage total.

Only successfully completed source checks are exported as ranking history. Failed, running, and deferred attempts are not ranking observations and are not included. Imported rows preserve their provider, depth, and normalization version. Visibility measures volume-weighted ranking strength in Google’s Top 20. 100 means every measured keyword ranks #1. Rankings below #20 do not add Visibility. Shallow or failed checks are not treated as lost rankings. Top 10 checks do not update Visibility. Affected keywords still count toward its coverage total.

Export requestedDepth whenever the source instance has it. A null value remains valid when the source did not store a depth, and the completed import reports those rows as history_unknown_depth.

Version 5 history does not distinguish failed attempts from successful no-match observations. bisibility rejects it rather than importing ambiguous ranking data. Update the source instance and create a version 7 export.

Success returns 201.

{
  "counts": {
    "keywords": 1,
    "keywords_created": 1,
    "keywords_skipped": 0,
    "history": 1,
    "history_received": 1
  },
  "job_id": "imp_abcdefghijklmnopqrstuvwx",
  "state": "done"
}

Every v7 package includes every section, including empty arrays:

Count	Meaning
`history_unknown_depth`	When present, received history rows with `requestedDepth: null`.
`alert_rules`, `alert_rules_skipped`	Imported and skipped alert rules.
`competitors`	Imported competitors.
`notification_preferences`	Imported notification preferences.
`saved_views`	Imported saved views.

Chunked session import

Use sessions when the package is large enough that one request may exceed body limits or timeout. A session has three phases: create, upload chunks, finalize.

1. Create the Session

POST /api/v1/cloud/import/sessions
Authorization: Bearer mig_...
Content-Type: application/json

{
  "version": 7,
  "chunk_count": 3,
  "source_project_id": "prj_abcdefghijklmnopqrstuvwx",
  "totals": {
    "keywords": 650,
    "rank_checks": 12000
  }
}

New exporters send version 7; a destination also accepts version 6 session manifests. chunk_count must be between 1 and 500. source_project_id is required and prevents importing a project into itself. totals is optional and is stored with the session manifest. Success returns 201.

{
  "session_id": "imp_abcdefghijklmnopqrstuvwx",
  "state": "receiving",
  "chunk_limits": {
    "max_body_bytes": 8388608,
    "max_history_rows": 25000,
    "max_keywords": 500
  }
}

Only one live receiving or importing session is allowed per token. A second live session returns 409.

2. Upload Chunks

Upload each chunk by zero-based index:

PUT /api/v1/cloud/import/sessions/imp_abcdefghijklmnopqrstuvwx/chunks/0
Authorization: Bearer mig_...
Content-Type: application/json

Keyword chunks carry keyword rows:

{
  "checksum": "sha256:4f8d72fb6ca13e3140cfb4251850959f3a7a3bfc6f3d898cf0f71ba1a76218bb",
  "kind": "keywords",
  "keywords": [{ "id": "kw_abcdefghijklmnopqrstuvwx", "keyword": "rank tracker api", "device": "desktop", "location": "United States", "location_key": "US", "tags": [], "rankingHistory": [] }]
}

Section chunks carry non-keyword package sections and optional source keyword ids used to map imported alert targets:

{
  "checksum": "sha256:f25d1e411a68b72a52872a86c2bf94fba85436aecc335dc172826a7d2be4197e",
  "kind": "sections",
  "sections": {
    "competitors": [{ "id": "cmp_abcdefghijklmnopqrstuvwx", "domain": "example.com", "label": "Example" }],
    "source_keyword_ids": {
      "kw_abcdefghijklmnopqrstuvwx": {
        "text": "rank tracker api",
        "location": "United States",
        "location_key": "US",
        "device": "desktop"
      }
    }
  }
}

The checksum is the v7 canonical chunk-content identity for idempotent retries. Retrying the same {sessionId, index} with the same checksum returns 200; retrying that index with a different checksum returns 409. Clients should compute the sha256: value over the canonical JSON body { version: 7, ...chunk }, excluding the checksum field, before gzip compression. To gzip a chunk, send the gzip-compressed JSON body with:

Content-Encoding: gzip

The body limit applies before and after decompression. Oversized chunks return 413. Success returns:

{
  "state": "receiving",
  "chunks_received": 2,
  "chunk_count": 3
}

3. Finalize

Finalize after every chunk has been accepted:

POST /api/v1/cloud/import/sessions/imp_abcdefghijklmnopqrstuvwx/finalize
Authorization: Bearer mig_...
Content-Type: application/json

The body may be empty or {}. If chunks are missing, finalize returns 409. If another finalize is already importing the session, it returns 409. Once the session is done, a repeated finalize call returns the completed job response.

{
  "job_id": "imp_abcdefghijklmnopqrstuvwx",
  "state": "done",
  "counts": {
    "keywords": 650,
    "keywords_created": 640,
    "keywords_skipped": 10,
    "history": 12000,
    "history_received": 12000,
    "history_unknown_depth": 0
  }
}

Crash Resume

Persist session_id, chunk_count, and every chunk checksum on the client. After a client crash, re-upload all chunks whose success was not recorded. The server accepts already stored chunks when the checksum matches. If the connection drops during finalize, call finalize again. A 200 means the session completed. A 409 means chunks are still missing or a finalize is still running. Stale receiving and importing jobs are marked failed by maintenance after 30 minutes, after which a new migration token and session are required.

Status Codes

Status	Meaning
`200`	Chunk accepted, session finalized, or compatibility returned.
`201`	Single request import completed or session created.
`400`	Invalid JSON, invalid manifest, invalid chunk, or invalid index.
`401`	Missing or malformed migration token.
`409`	Live session conflict, chunk checksum conflict, missing chunks, already finalizing, or self-import (package exported from the destination project itself, code `self_import`).
`413`	Request body or buffered session payload is too large.
`419`	Migration token is invalid, expired, or already used.
`423`	Destination project is in migration hold.
`429`	Rate limit exceeded.
`500`	Import failed after the job started.

Environment Knobs

Variable	Default	Effect
`BISIBILITY_MIGRATION_IMPORT_MAX_BODY_BYTES`	`8388608`	Maximum JSON body size for single request imports and session requests.
`BISIBILITY_MIGRATION_TOKEN_TTL_MINUTES`	`60`	Migration token lifetime in minutes, clamped between `5` and `1440`.
`BISIBILITY_MIGRATION_HOLD_TTL_HOURS`	`24`	Hours before maintenance releases an expired migration hold.
`BISIBILITY_MIGRATION_EXPORT_MAX_KEYWORDS`	`500`	Maximum keywords included in a downloadable migration package.
`BISIBILITY_MIGRATION_MAX_KEYWORDS`	`50000`	Maximum keywords allowed for direct migration push.
`BISIBILITY_MIGRATION_TARGET_ALLOWLIST`	empty	Comma-separated hostnames allowed as migration targets, with `*.suffix` wildcard support. Empty allows any public host.

Existing App Surfaces

The app also implements instance-import state with server actions:

Function	Purpose
`mintMigrationToken`	Create a single-use migration token for a project.
`regenerateMigrationToken`	Consume any active token and create a replacement.
`revokeMigrationToken`	Consume an active migration token.
`advanceCloudImportJob`	Advance a job through `receiving`, `importing`, `done`, or `failed`.

In-App Wizard

Open /cloud/import, generate or paste a migration token, then upload the JSON package from the wizard. The wizard uses the same import handlers as the REST endpoints.

Get started

Build and automate

Concepts

Self-hosting

Product guides

API workflows

REST resource guides

SDKs

AI / Agents

Endpoints

Authentication

Migration Tokens

Compatibility Preflight

Single Request Import

Chunked session import

1. Create the Session

2. Upload Chunks

3. Finalize

Crash Resume

Status Codes

Environment Knobs

Existing App Surfaces

In-App Wizard

​Endpoints

​Authentication

​Migration Tokens

​Compatibility Preflight

​Single Request Import

​Chunked session import

​1. Create the Session

​2. Upload Chunks

​3. Finalize

​Crash Resume

​Status Codes

​Environment Knobs

​Existing App Surfaces

​In-App Wizard

Endpoints

Authentication

Migration Tokens

Compatibility Preflight

Single Request Import

Chunked session import

1. Create the Session

2. Upload Chunks

3. Finalize

Crash Resume

Status Codes

Environment Knobs

Existing App Surfaces

In-App Wizard