UUIDs, short links, and compatibility

Sites, scenarios, runs, and other working resources have a public UUID. Use it in the API and saved links without relying on a sequential object number. Existing resources and links containing numeric IDs continue to work.

Choosing a format

V2 offers the same working methods as v1. Authentication, permissions, limits, and result content stay the same apart from declared identity fields. Direct export tokens and /api/export/… remain a separate interface.

Choose v2 for a new integration. An existing integration can remain on v1 until you have checked your client with the new format.

Your first UUID request

curl --fail-with-body "$BASE/api/v2/sites" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Accept: application/json'

The equivalent format choice in v1:

curl --fail-with-body "$BASE/api/v1/sites" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'X-Identifier-Format: uuid' \
  -H 'Accept: application/json'

Set BASE and API_KEY in protected environment variables. Do not put the key in a link or a visitor-facing browser script. Creating an API key.

In UUID mode a known resource includes these identity fields. This example omits unrelated fields:

{
  "id": "019a0740-dc00-7abc-8def-0123456789ab",
  "public_id": "019a0740-dc00-7abc-8def-0123456789ab",
  "short_id": "~1CULXneEtSGKRmiQRog8Zx",
  "legacy_id": 175,
  "code": "catalog",
  "name": "Catalog"
}

Store id as your program's object reference. public_id explicitly identifies the canonical UUID; short_id is useful for a short link; legacy_id helps match the result to an existing integration. These are sample values: always use the identifiers returned by your own installation.

Passing an identifier

Declared resource parameters accept three forms. For example, one site:

/api/v2/sites/175
/api/v2/sites/019a0740-dc00-7abc-8def-0123456789ab
/api/v2/sites/~1CULXneEtSGKRmiQRog8Zx

These addresses refer to the same object in your installation if all values came from that object's response. The same rule applies to site_id, script_id, version_id, agent_id, connection_id, and other declared resource references in query parameters and JSON bodies. Use null if a nullable field has no selected relation.

{
  "site_id": "019a0740-dc00-7abc-8def-0123456789ab",
  "name": "Daily catalog"
}

This example chooses a site when creating a scenario. Read the method reference for its other parameters.

The short form encodes the complete UUID without losing data. Its initial ~ is required and letter case matters. Do not truncate UUIDs or remove characters. An invalid value does not create a new resource.

What stays unchanged

• Collected record keys, product SKUs, symbolic code values, and slugs.
• Version numbers, counters, dates, amounts, and row positions.
• cursor, next_cursor, after, and Last-Event-ID cursors.
• Your data, params, JSON fields, and export content.
• Existing tokens, external system identifiers, and file or artifact UUIDs.

In a run log, each row has a public id, while the response's cursor remains numeric. To continue, pass the previous response's cursor as after. Do not put a log row's UUID in after.

A UUID is a resource address, not a secret. A person with someone else's link still needs access to the workspace and site. An API key remains limited to its workspace regardless of the identifier format.

The scenario SDK and the exchange of jobs with your own agent retain their contracts. You do not need to replace every number inside a scenario with a UUID.

Updating an existing client

1. Keep the working v1 client without the new header during the transition.
2. Enable UUIDs for a separate test request. Store IDs as strings: do not call parseInt or Number, or calculate the next ID by adding one.
3. Match previously saved objects to new responses using legacy_id.
4. Check reads, filters, creation, and updates for the resources your client uses.
5. Switch to v2, or keep v1 with X-Identifier-Format: uuid.

Do not copy numeric IDs manually between separate installations: a local number may belong to another object. Preserve public identity alongside the data in backups. Sort by an object's date or another relevant field: the UUID issue time of an old record is not its original creation date.

For individual operations, see all API methods.