Server API reference

The routes your backend calls with a site's secret key, and every shape they take and return. Every route is under /v1/ on the platform's API address. Request and response bodies are JSON.

This page is made from the platform's API document, so it always matches the code. The rules behind the routes (versions, visibility, the owner, freshness) are in contracts/profile-sync.md, and the profile lifecycle guide walks through them with real requests.

openapi.json, beside this page, holds the same routes and shapes as an OpenAPI 3.1 document, for tools such as a client generator.

One site's profiles, which the partner's backend sends with the site's secret key: an upsert on every change, a delete when a profile goes, batches for bulk changes, and a paged list to reconcile, such as once a day. The rules are in contracts/profile-sync.md.

Authentication

secret_key: A site's secret key, sk_..., which the partner console makes and rotates under Keys and shows in full once. Send it with every request as Authorization: Bearer sk_..., over HTTPS, from the partner's servers only: never from a browser or an app, and never into a log. A key reaches only its own site's profiles, so a profile on another site is not found, even when the partner owns that site too. After a rotation, the replaced key keeps working for 24 hours, unless the console ends it sooner. A missing key, or one that does not work, gets 401 (contracts/profile-sync.md, "Authentication").

Operations

GET /v1/profiles

Lists the profiles the platform holds.

Lists every profile the platform holds for the site, deleted ones included, with the version of its last upsert or delete. Use it to reconcile, regularly, such as once a day, and never once per page view: compare the list with the site's own, by external id, and send again what differs. Upsert each profile the platform does not list or holds at a lower version than the site's. Delete, with a higher version, each profile the platform holds that the site no longer lists. Send those changes in batches (contracts/profile-sync.md, "Reconciliation").

A page holds up to 1,000 profiles, in byte order of external_id as ASCII sorts it: - and ., then digits, then A to Z, then _, then a to z. Pass a page's next as after to get the next page; the last page has no next. The site's database may sort the same ids in another order, so compare the two lists as sets rather than side by side.

Reconcile even when nothing changed. The AI assistant answers from the site's profiles only while a counted request arrived within the last 7 days (or another period the instance's operator set), and each page answered 200 counts (contracts/profile-sync.md, "Keeping the copy fresh").

Send the site's secret key as Authorization: Bearer sk_....

Authentication: secret_key (see Authentication).

Parameters:

Responses:

Header on 429: Retry-After, integer. How many seconds to wait before sending the request again: a whole number, at least 1.

Header on 503: Retry-After, integer. Sent only while the instance is switching to another server: how many seconds to wait before sending the request again.

Example response, 200:

{
  "next": "marco",
  "profiles": [
    {
      "deleted": false,
      "external_id": "anna",
      "version": 42
    },
    {
      "deleted": true,
      "external_id": "ines",
      "version": 17
    },
    {
      "deleted": false,
      "external_id": "marco",
      "version": 7
    }
  ]
}

POST /v1/profiles/batch

Upserts and deletes profiles in a batch.

Sends up to 100 upserts and deletes in one request. Use it for bulk changes, such as an initial import or what a reconciliation found, rather than one call per profile. A site may send about 10 requests a second, so 10 batches of 100 a second sync 100,000 profiles in under two minutes.

Each item is decided on its own, as if sent alone with PUT or DELETE, and gets one result, in the items' order. A rejected item does not stop the others or undo them, and items that name the same profile apply in the order sent. The batch is saved as one: the changes it applies take effect together, or none of them does.

Safe to repeat: after a timeout or a 5xx, send the whole batch again. Usually none of it applied. If it was saved just before the failure, the items it applied come back unchanged, and the others as they did before. No idempotency key is needed.

Send total, how many profiles the site lists in all, during an initial import and whenever it changes: the partner console shows "imported of total". A batch answered 200 also keeps the site's profiles fresh for the AI assistant (contracts/profile-sync.md, "Keeping the copy fresh").

Send the site's secret key as Authorization: Bearer sk_....

Authentication: secret_key (see Authentication).

Request body (required): application/json: ProfileBatch. The items, and optionally the site's total.

Example request:

{
  "items": [
    {
      "action": "upsert",
      "external_id": "anna",
      "fields": {
        "assistant_name": {
          "value": "Anna",
          "visibility": "public"
        },
        "headline": {
          "value": "Classic and sports massage, Baixa",
          "visibility": "public"
        },
        "name": {
          "value": "Anna, massage",
          "visibility": "public"
        }
      },
      "owner": "sg-owner-anna",
      "version": 42
    },
    {
      "action": "upsert",
      "external_id": "marco",
      "fields": {
        "headline": {
          "value": "Thai massage, Estrela",
          "visibility": "public"
        },
        "name": {
          "value": "Marco Ferreira",
          "visibility": "public"
        },
        "services": {
          "value": "Thai massage on a floor mat, 60 or 90 minutes.",
          "visibility": "ai_only"
        }
      },
      "owner": "sg-owner-marco",
      "version": 7
    },
    {
      "action": "delete",
      "external_id": "ines",
      "version": 17
    }
  ],
  "total": 48
}

Responses:

Header on 429: Retry-After, integer. How many seconds to wait before sending the request again: a whole number, at least 1.

Header on 503: Retry-After, integer. Sent only while the instance is switching to another server: how many seconds to wait before sending the request again.

Example response, 200:

{
  "results": [
    {
      "external_id": "anna",
      "outcome": "applied",
      "version": 42
    },
    {
      "external_id": "marco",
      "outcome": "unchanged",
      "version": 7
    },
    {
      "external_id": "ines",
      "outcome": "rejected",
      "reason": "version-reused"
    }
  ]
}

GET /v1/profiles/{external_id}

Shows the platform's copy of a profile.

Shows what the platform holds for one of the site's profiles, so the site can check what arrived: the version, when it arrived, the public and AI-only fields with their values, and the names of the private ones. Never a private value, and never the owner. It is for debugging: a sync never needs it, and reading it does not keep the site's profiles fresh for the AI assistant.

A deleted profile shows deleted: true and no fields. A profile the platform never had for the key's site gets 404.

Send the site's secret key as Authorization: Bearer sk_....

Authentication: secret_key (see Authentication).

Parameters:

Responses:

Header on 429: Retry-After, integer. How many seconds to wait before sending the request again: a whole number, at least 1.

Header on 503: Retry-After, integer. Sent only while the instance is switching to another server: how many seconds to wait before sending the request again.

Example response, 200:

{
  "deleted": false,
  "external_id": "anna",
  "fields": {
    "assistant_name": {
      "value": "Anna",
      "visibility": "public"
    },
    "headline": {
      "value": "Classic and sports massage, Baixa",
      "visibility": "public"
    },
    "name": {
      "value": "Anna, massage",
      "visibility": "public"
    },
    "prices": {
      "value": "Classic massage 60 minutes: 45 EUR. Sports massage 90 minutes: 60 EUR.",
      "visibility": "ai_only"
    },
    "services": {
      "value": "Classic massage, 60 minutes. Sports massage, 90 minutes.",
      "visibility": "ai_only"
    }
  },
  "private_fields": [
    "phone"
  ],
  "synced_at": "2026-10-12T09:20:00Z",
  "unflagged_fields": [
    "years_active"
  ],
  "version": 42
}

PUT /v1/profiles/{external_id}

Upserts a profile.

Creates or replaces the platform's copy of one of the site's profiles. Send it each time a profile is created or changes on the site, with a version above the last one sent for that profile. For many profiles at once, such as an initial import, send them in batches of up to 100 with POST /v1/profiles/batch rather than one call each.

The platform applies the upsert only when its version is above the one it holds, a deleted profile's included. It answers 200 with the outcome: applied, unchanged (the same version and content again: a retry) or stale (a newer change arrived first). Neither unchanged nor stale is a failure. Private values are dropped on arrival, and only their field names are kept.

Safe to repeat: a retry carries the same version and content, so it cannot apply twice, and in any order the highest version wins. No idempotency key is needed. Keep each change queued until it gets a 200, and send it again after a 429 or a 5xx; any other error comes back the same until the request is fixed (contracts/profile-sync.md, "Ordering, retries and idempotency").

A rejection is a 422 whose type names the reason, and the partner console lists it for 30 days. An upsert answered 200 or rejected also keeps the site's profiles fresh for the AI assistant (contracts/profile-sync.md, "Keeping the copy fresh").

Send the site's secret key as Authorization: Bearer sk_....

Authentication: secret_key (see Authentication).

Parameters:

Request body (required): application/json: ProfileUpsert. The whole profile: its version, its owner and every field the platform should have. Fields left out are gone from the copy once the upsert applies.

Example request:

{
  "fields": {
    "assistant_name": {
      "value": "Anna",
      "visibility": "public"
    },
    "headline": {
      "value": "Classic and sports massage, Baixa",
      "visibility": "public"
    },
    "name": {
      "value": "Anna, massage",
      "visibility": "public"
    },
    "phone": {
      "value": "+351 000 000 201",
      "visibility": "private"
    },
    "prices": {
      "value": "Classic massage 60 minutes: 45 EUR. Sports massage 90 minutes: 60 EUR.",
      "visibility": "ai_only"
    },
    "services": {
      "value": "Classic massage, 60 minutes. Sports massage, 90 minutes.",
      "visibility": "ai_only"
    },
    "years_active": {
      "value": "8"
    }
  },
  "owner": "sg-owner-anna",
  "version": 42
}

Responses:

Header on 429: Retry-After, integer. How many seconds to wait before sending the request again: a whole number, at least 1.

Header on 503: Retry-After, integer. Sent only while the instance is switching to another server: how many seconds to wait before sending the request again.

Example response, 200:

{
  "external_id": "anna",
  "outcome": "applied",
  "version": 42
}

Example response, 422:

{
  "field": "assistant_name",
  "status": 422,
  "title": "Invalid field",
  "type": "/problems/invalid-field"
}

DELETE /v1/profiles/{external_id}

Deletes a profile.

Erases the platform's copy of one of the site's profiles. Send it when a profile leaves the site, with a version above the profile's last upsert, since a delete is a change too. For many deletes at once, send them in batches with POST /v1/profiles/batch.

When the version is above the one held, the profile's fields and owner go at once. The platform keeps only the external id, the version and the time of the delete, so that an older upsert arriving late cannot bring the profile back. A delete of a profile the platform never had keeps that record too. To bring a deleted profile back, upsert it with a version above the delete's.

The answer is 200 with the same outcome an upsert gets. Safe to repeat: a retry carries the same version, so it cannot apply twice, and no idempotency key is needed. A delete answered 200 or rejected also keeps the site's profiles fresh for the AI assistant (contracts/profile-sync.md, "Keeping the copy fresh").

Send the site's secret key as Authorization: Bearer sk_....

Authentication: secret_key (see Authentication).

Parameters:

Responses:

Header on 429: Retry-After, integer. How many seconds to wait before sending the request again: a whole number, at least 1.

Header on 503: Retry-After, integer. Sent only while the instance is switching to another server: how many seconds to wait before sending the request again.

Example response, 200:

{
  "external_id": "anna",
  "outcome": "applied",
  "version": 43
}

Example response, 422:

{
  "status": 422,
  "title": "Version reused",
  "type": "/problems/version-reused"
}

Schemas

BatchItem

One item of a batch, by its action: an upsert, which is the body of a PUT plus the profile's external_id, or a delete, with external_id and version.

One of these forms:

action is upsert. An upsert: the body of PUT /v1/profiles/{external_id}, plus the profile's external_id.

Every field of ProfileUpsert, and these:

action is delete. A delete, as DELETE /v1/profiles/{external_id} makes it.

BatchItemResult

What one item of a batch did, by its outcome: applied, unchanged or stale, as PUT and DELETE answer them, or rejected, with the same reason a PUT or a DELETE would get.

One of these forms:

outcome is applied. Its version was above the one held, or none was: it replaced the copy.

outcome is unchanged. The same version and content as the copy held: a retry, which changed nothing.

outcome is stale. A lower version than the one held: a newer change arrived first, and this one changed nothing.

outcome is rejected. Rejected, and listed in the partner console for 30 days. The item changed nothing; fix it before sending it again.

FieldVisibility

The visibility flags a site may send with a field. public: kept, read by the AI assistant, and shown on the widget's profile card for name, headline and assistant_name. ai_only: kept, and read only by the AI assistant, which may repeat it to visitors. private: only the field's name is kept; the value is dropped on arrival and nothing reads it. Any other value, or none, is private.

A string, one of:

• public
• ai_only
• private

KeptField

A field whose value the platform keeps: a public or an AI-only one.

KeptVisibility

The visibility of a field whose value the platform keeps. public: the AI assistant reads it, and the widget's profile card shows it for name, headline and assistant_name. ai_only: only the AI assistant reads it. A private value is never kept.

A string, one of:

• public
• ai_only

Problem

An error, as an RFC 9457 problem document.

ProfileBatch

Up to 100 upserts and deletes of the site's profiles, each decided on its own: a rejected item stops no other. The batch is saved as one: its changes take effect together, or none does.

ProfileBatchResults

What each item of a batch did.

ProfileCopy

The platform's copy of one profile, for the site to check what arrived. It never holds a private value, which the platform drops on arrival, nor the owner, of whom the platform keeps only a fingerprint.

ProfileUpsert

A profile as the site sends it: its version, its owner and its fields. It replaces the platform's copy when its version is above the one held, a deleted profile's included (contracts/profile-sync.md, "Upsert").

ProfileVersion

A profile the platform holds and the version of its last change, so the site can send again what differs.

ProfileVersionPage

One page of the profiles the platform holds for the site, deleted ones included, in byte order of external_id.

RejectedProblem

A 422 on a route that upserts or deletes a profile: a rejection, whose type names the reason and which the partner console lists for 30 days, or a request the platform could not read (about:blank, a plain problem), which the console does not list. Either way nothing applied, and the same request gets the same answer until it is fixed.

RejectionReason

Why the platform rejected an upsert or a delete. The partner console lists each rejection for 30 days, with the field when there is one, never the content (contracts/profile-sync.md, "Rejections"). owner-missing: the upsert has no owner, or it is empty or longer than 128 characters. invalid-field: a field name breaks its pattern, a value is empty or holds U+0000, there is no name field, or assistant_name is longer than 60 characters, has a line break or holds an invisible formatting character. too-large: more than 100 fields, a value longer than 4,000 characters, or more than 16,000 characters of public and AI-only values in all. version-reused: the version is the one held, with other content; give every change a new version.

A string, one of:

• owner-missing
• invalid-field
• version-reused
• too-large

SentField

One field of a profile, as the site sends it: its value, and who may see it.

SyncOutcome

What an upsert or a delete the platform accepted did. applied: its version was above the one held, or none was, and it replaced the copy. unchanged: the same version and the same content as the copy held, so it was a retry and changed nothing. stale: a lower version than the one held, so a newer change arrived first and this one changed nothing. Neither unchanged nor stale is a failure, and neither needs anything sent again.

A string, one of:

• applied
• unchanged
• stale

SyncResult

What an upsert or a delete did (contracts/profile-sync.md, "Versions"). A rejection is a 422 problem instead, whose type names the reason.