API docs

PromART API

AI-visibility (GEO) analytics, fact-checked fixes and optional API delivery.

PromART measures how AI assistants talk about your business (measured live today: ChatGPT, Gemini and Claude; more engines are in development, see GET /v1/engines), explains why, and writes fact-checked fixes. The main product is the analytics panel: visibility, share of voice, position, sentiment, cited sources, competitors, trends, raw answers, recommendations and PDF reports. The panel uses exactly the endpoints documented here.

Guide

Authentication

Every /v1 call (except the public ones marked No auth) needs a Bearer token. There are two kinds:

Token Where it comes from What it can do
sess_… panel session POST /v1/sessions with the workspace API key (30 days) everything; works on every plan
sk_live_… API key shown once when the workspace is created everything, but only on plans with API access (optimize, agency, agency_client, enterprise); other plans get 403 api_access_required
Authorization: Bearer sk_live_…

Rate limits depend on the plan; a 429 carries Retry-After. POST requests may send an Idempotency-Key header: a repeated key replays the first response (Idempotent-Replayed: true).

Measurement and analytics

Measurement (/v1/runs, /v1/answers, /v1/visibility, /v1/share-of-voice, /v1/citations) and analytics (/v1/overview, /v1/trends, /v1/competitors, /v1/sources, /v1/prompt-metrics, /v1/report, /v1/report.pdf) take the same filters: brand_id, engine, language, from, to (YYYY-MM-DD, inclusive). Analytics compare the period with the previous period of the same length (default: the last 28 days). Weeks start on Monday.

Fixes: applied by hand from the panel

Every generated change (GET /v1/content/items) carries placement (which URL, where on the page, numbered steps, the current text it replaces, and each part ready to copy) and facts (the confirmed facts it is written from). The flow without the API delivery add-on:

  1. proposed → POST /v1/content/{id}/approve → approved (ready to apply).
  2. The client pastes it into the site and calls POST /v1/content/{id}/applied → live; an experiment opens (re-measure after the pickup window, then keep or roll back). New pages use POST /v1/pages/{id}/published with the real URL instead.
  3. If the experiment shows no lift (or the client rolls back), the change becomes remove_requested with the text to remove; POST /v1/content/{id}/removed → rolled_back.

Google Business Profile changes stay automatic on every plan: approving gbp_profile / gbp_post writes them to Google (feature flag google_bp).

API delivery (paid add-on)

With the API delivery add-on (api_delivery_enabled on the workspace, see GET /v1/usage add_ons), approving a site change makes it live immediately and your backend fetches it while rendering. Without the add-on these endpoints return 403 addon_required:

What Call Use it to
Changes for an existing page GET /v1/content?url=<page URL> meta description, answer block, FAQ, JSON-LD schema and blocks[]
Only the section replacements GET /v1/pages/{url}/blocks (URL path-escaped) or GET /v1/pages/blocks?url= replace/insert specific sections
New pages to create GET /v1/pages/new approved pages: suggested URL, title, sections (with tables), schema, internal links
Confirm a new page is live POST /v1/pages/{id}/published tell PromART the real URL so it can measure the page

Only changes delivered through the API (delivery: api) are served; changes the client applied by hand are already on the page. Cache responses for up to 60 s (Cache-Control: private, max-age=60).

Applying blocks

Each block is {block_id, selector, action, html, fact_ids, status}. Find the first element matching the CSS selector in your rendered HTML and apply action:

action effect
replace replace the element (outer HTML) with html
append insert html as the element's last child
prepend insert html as the element's first child
before insert html immediately before the element
after insert html immediately after the element

If the selector matches nothing, skip the block. html is already sanitized by PromART: only p br h2 h3 h4 ul ol li strong em b i table thead tbody tr th td a (links only to your own hosts), no scripts, styles or attributes other than a[href].

Verifying the signature

GET /v1/content, GET /v1/pages/{url}/blocks, GET /v1/pages/blocks and GET /v1/pages/new responses carry

X-Sachino-Signature: sha256=<hex HMAC-SHA256(signing_secret, exact response body bytes)>

signing_secret comes from GET /v1/me. Verify against the raw bytes before parsing JSON, with a constant-time comparison.

Node:

JavaScript
const crypto = require('crypto');
const ok = (raw, header, secret) => {
  const want = 'sha256=' + crypto.createHmac('sha256', secret).update(raw).digest('hex');
  return header && header.length === want.length &&
    crypto.timingSafeEqual(Buffer.from(header), Buffer.from(want));
};

PHP:

PHP
$want = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($want, $_SERVER['HTTP_X_SACHINO_SIGNATURE'] ?? $header);

Go:

Go
m := hmac.New(sha256.New, []byte(secret))
m.Write(raw)
ok := hmac.Equal([]byte(header), []byte("sha256="+hex.EncodeToString(m.Sum(nil))))

Fallback rule (required)

PromART must never break your site. If the API call errors, times out (we suggest an 800 ms timeout), returns a non-2xx status (including 403 addon_required), or the signature does not match, render your original page unchanged. Never block page rendering on PromART.

IndexNow

GET /v1/indexnow-key returns your workspace's IndexNow key and the file your developer must host on every domain: https://<domain>/<key>.txt, plain text, containing only the key, HTTP 200, no redirect. After every content.published event (a change goes live through the API or is marked applied, or a new page is confirmed) PromART submits the changed URLs to IndexNow; each submission and its result appears in GET /v1/actions (channel bing). The indexnow_key site check turns ok once the file is reachable.

Webhooks

Subscribe with POST /v1/webhooks. Events: run.completed, visibility.changed, content.proposed, content.approved, content.published, content.removal_requested, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request (or * for all).

Each delivery is a POST with JSON body {id, type, created_at, data} and headers X-Sachino-Event: <type> and X-Sachino-Signature: sha256=<hex HMAC-SHA256(webhook secret, body)> (the secret is returned when the webhook is created). Non-2xx responses are retried 3 times.

Account integrations and feature flags

Google Business Profile (google_bp, scope business.manage), Search Console (gsc) and GA4 (ga4, analytics.readonly) connect through Google OAuth; tokens are stored encrypted. Cloudflare (cloudflare) takes a pasted API token scoped to the zone's bot settings and is used only to allow AI crawlers. cloudflare and google_bp are behind server feature flags: when a flag is off, the related endpoints return 403 with code feature_disabled, and GET /v1/integrations lists the kind with enabled: false.

Errors

Errors use one envelope: {"error": {"code": "...", "message": "..."}}. Codes: unauthorized (401), plan_limit (402), api_access_required (403: an API key on a plan without API access; the panel uses sessions and works on every plan), addon_required (403: API delivery add-on not enabled), feature_disabled (403), not_found (404), invalid_request / invalid_json (400), rate_limited (429), internal (500). Branch on code: it is coarse and stable. A /v1 path that does not exist answers 404 with code not_found in this envelope too, and a method a /v1 path does not support answers 405 with code invalid_request and an Allow header.

An error with a more specific cause also carries reason, a stable key of its message such as http.err.brand_id_required or core.err.not_found.brand, and params, the values in that message (left out when there are none). A param that names something (a plan, a status, an engine) is its code, as in English messages. Its message is then in the response language (see Language); in English it is the same text as before reason existed.

JSON
{"error": {"code": "api_access_required",
           "message": "plan monitor does not include API access; use the panel, or upgrade to Optimize or higher",
           "reason": "http.err.api_access_required", "params": {"plan": "monitor"}}}

Language

Texts written by PromART (error messages, notes, recommendations, placement steps, alerts, the invite page) can be returned in Georgian, Russian or English. Choose with the lang query parameter (ka, ru or en, on any endpoint) or the Accept-Language header (the supported language with the highest q-value wins; lang overrides it). Without either, or with only unsupported languages, responses are in English, exactly as before. Every response names its language in Content-Language, which browsers may read (Access-Control-Expose-Headers), and sends Vary: Accept-Language, except responses that are the same in every language: the site content of GET /v1/content and GET /v1/pages/{url}/blocks, /healthz, the fonts and the files of the docs page send neither. /docs is rendered in the requested language too (Georgian, Russian or English, with Vary: Accept-Language); /openapi.yaml is English only and sends Content-Language: en without Vary. A POST replayed for its Idempotency-Key comes back in the language of the first request, with that Content-Language. Codes, IDs and your own data (brand names, facts, prompts, AI answers, generated site content) are never translated.

Parameters every endpoint takes

Every /v1 endpoint and the invite pages take these two parameters, which choose the language of the texts PromART writes. Each endpoint below lists them in one row.

ParameterType and description
langquerystring
Language of the texts PromART writes into the response (error messages, notes, recommendations, placement steps, alerts, the invite page): ka Georgian, ru Russian, en English. Overrides Accept-Language; any other value is ignored. Codes, IDs and your own data are never translated. See Language in the guide.

Allowed values: ka, ru, en

Accept-Languageheaderstring
Used when lang is absent: the supported language (ka, ru, en) with the highest q-value wins (the first one on a tie); without one, the response is in English.

Analytics

KPIs with deltas, weekly trends, competitors, sources, prompt results, PDF report.

KPIs for the period and the previous period of the same length

GET/v1/overview

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Default period is the last 28 days. Visibility, share of voice, average position (lower is better) and sentiment for the client.

Parameters

ParameterType and description
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Inclusive
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Overview

    • from string date
    • to string date
    • prev_from string date
    • prev_to string date
    • current KPI
    • previous KPI

The client and every brand engines named, with previous-period values

GET/v1/competitors

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Inclusive
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json CompetitorRow[]

    • name string
    • is_client boolean
    • mentions integer
    • visibility_pct number
    • sov_pct number
    • avg_position number
    • avg_sentiment number
    • prev_visibility_pct number
    • prev_sov_pct number

Sources cited by AI engines, by domain or by URL, with counts per engine

GET/v1/sources

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Inclusive
byquerystring

Allowed values: domain, urlDefault: domain

limitqueryinteger

Default: 100At most 1000

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json SourceRow[]

    • url string
      Only with by=url
    • domain string
    • owner string

      Allowed values: client, competitor, third_party

    • count integer
      Answers citing it
    • share_pct number
    • engines map<string, integer>

Visibility and position per prompt, overall and per engine (lowest visibility first)

GET/v1/prompt-metrics

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Inclusive
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json PromptRow[]

    • prompt_id string
    • text string
    • language string
    • target_url string
    • answers integer
    • visibility_pct number
    • avg_position number
    • top_competitor string
    • engines map<string, EngineCell>

PDF report for a brand and period

GET/v1/report.pdf

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

KPIs with deltas, weekly visibility chart (12 weeks), competitors, engines, cited sources, fixes and experiments, recommendations. Default period is the last 28 days. Labels, numbers and dates are in the response language (lang, else Accept-Language, else English; see Language); brand names, domains and URLs stay as they are.

Parameters

ParameterType and description
brand_idqueryRequiredstring
enginequerystring
languagequerystring
Answers in this language only (a data filter, not the PDF's language)
fromquerystring date
toquerystring date
Inclusive
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 PDF (attachment), named sachino-<domain>-<to>.pdf

    application/pdf string binary

  • 400 Error

    application/json Error

  • 404 Error

    application/json Error

Delivery

Paid API delivery add-on — what the client's backend calls while rendering pages.

Live changes for one page (signed; API delivery add-on)

GET/v1/content

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Paid API delivery add-on; without it the response is 403 addon_required. Returns the changes delivered through the API (delivery: api). Call while rendering the page. Verify X-Sachino-Signature and fall back to the original page on any error, timeout (800 ms suggested), non-2xx status or signature mismatch.

Parameters

ParameterType and description
urlqueryRequiredstring uri
Page URL (normalized by PromART)
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 Delivery

    Headers

    • X-Sachino-Signature string
      sha256= + hex(HMAC-SHA256(signing_secret from GET /v1/me, exact response body bytes))
    • Cache-Control string

    application/json Delivery

    • url string
    • version integer
      Increases with every published change for this URL
    • meta_description string
    • answer_block string
    • faq object[]
      Fields: 3
      • q string
      • a string
      • fact_ids string[]
    • schema object
      JSON-LD
    • blocks BlockItem[]
    • content_ids string[]
    • signature string
      Legacy: HMAC of the body without this field. Verify the X-Sachino-Signature header instead.
  • 400 Error

    application/json Error

  • 401 Error

    application/json Error

  • 403 addon_required: the API delivery add-on is not enabled for this workspace

    application/json Error

Section blocks for a page, by query (signed; API delivery add-on)

GET/v1/pages/blocks

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Paid API delivery add-on; without it the response is 403 addon_required. Only blocks delivered through the API are returned as live.

Parameters

ParameterType and description
urlqueryRequiredstring uri
statusquerystring
Default only live blocks; all includes proposed and past ones

Allowed values: all

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 Blocks

    Headers

    • X-Sachino-Signature string
      sha256= + hex(HMAC-SHA256(signing_secret from GET /v1/me, exact response body bytes))

    application/json BlockItem[]

    • content_id string
    • block_id string
    • selector string
    • action string

      Allowed values: replace, append, prepend, before, after

    • html string
    • fact_ids string[]
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

  • 400 Error

    application/json Error

  • 403 addon_required: the API delivery add-on is not enabled for this workspace

    application/json Error

Section blocks for a page (signed; API delivery add-on)

GET/v1/pages/{url}/blocks

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Replacement text for specific sections of an existing page. url is the page URL, path-escaped (encodeURIComponent). Paid API delivery add-on; without it the response is 403 addon_required.

Parameters

ParameterType and description
urlpathRequiredstring

Example: https%3A%2F%2Fexample.com%2Fservices

statusquerystring
Default only live blocks; all includes proposed and past ones

Allowed values: all

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 Blocks

    Headers

    • X-Sachino-Signature string
      sha256= + hex(HMAC-SHA256(signing_secret from GET /v1/me, exact response body bytes))

    application/json BlockItem[]

    • content_id string
    • block_id string
    • selector string
    • action string

      Allowed values: replace, append, prepend, before, after

    • html string
    • fact_ids string[]
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

  • 400 Error

    application/json Error

  • 403 addon_required: the API delivery add-on is not enabled for this workspace

    application/json Error

New pages to create (signed; API delivery add-on)

GET/v1/pages/new

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Approved pages with a suggested URL, title, sections (HTML incl. tables), JSON-LD schema and internal links. Create the page, then confirm with POST /v1/pages/{id}/published. Paid API delivery add-on; without it the response is 403 addon_required (in the panel, new pages appear in GET /v1/content/items?kind=page).

Parameters

ParameterType and description
brand_idquerystring
statusquerystring
Default approved and live

Allowed values: approved, live, proposed

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 Pages (content items of kind page; see body.page)

    Headers

    • X-Sachino-Signature string
      sha256= + hex(HMAC-SHA256(signing_secret from GET /v1/me, exact response body bytes))

    application/json Content[]

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from
  • 403 addon_required: the API delivery add-on is not enabled for this workspace

    application/json Error

Confirm where a new page went live

POST/v1/pages/{id}/published

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Marks the page live, points matching prompts at it, logs an action, emits content.published, submits the URL to IndexNow and opens an experiment to measure it.

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • url string uri
    Real URL on the brand's domain; default the suggested URL

Responses

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from
  • 400 Error

    application/json Error

Pages

Propose new pages for uncovered services

POST/v1/pages/generate

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • brand_id string Required
  • max integer

    Default: 3At most 10

Responses

  • 201 Proposed pages

    application/json Content[]

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from

Site checks

Retrieval audit with developer instructions

GET/v1/site-checks

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Indexing (Search Console when connected), AI bot access in robots.txt and at the CDN, sitemap, IndexNow key file, fetchability, noindex, text visible without JavaScript, speed. Re-crawled when older than 1 hour or with refresh.

Parameters

ParameterType and description
brand_idqueryRequiredstring
refreshquerystring

Allowed values: 1, true

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json SiteCheck[]

    • id string
    • check string

      Allowed values: robots_ai_bots, cdn_ai_bots, sitemap, indexnow_key, fetch, noindex, js_rendering, speed, google_index

    • target string
      Domain or URL
    • status string

      Allowed values: ok, warn, fail, unknown

    • detail string
    • instruction string
      Exact task for the client or developer
    • fix string
      Automatic fix PromART can run, e.g. cloudflare:allow_ai_crawlers
    • source string

      Allowed values: crawl, gsc, cloudflare

    • checked_at string date-time

Workspace IndexNow key and hosting instructions

GET/v1/indexnow-key

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json IndexNowInfo

    • key string
    • files object[]
      Fields: 5
      • brand_id string
      • domain string
      • url string
        https://<domain>/<key>.txt
      • content string
        Exact file body (the key)
      • status string
        From the last site check

        Allowed values: ok, fail, unknown

    • instructions string[]

Integrations

Connections, available kinds and client wording

GET/v1/integrations

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json object

    • items Integration[]
      Fields: 12
      • id string
      • brand_id string
      • kind string

        Allowed values: google_bp, gsc, ga4, cloudflare

      • status string

        Allowed values: invited, pending, connected, needs_selection, error, revoked

      • account string
      • scopes string
      • config map<string, string>
      • invite_email string
      • last_sync_at string date-time
      • last_error string
      • created_at string date-time
      • updated_at string date-time
    • kinds map<string, IntegrationKind>
      Fields: 4
      • scope string
        Google OAuth scope
      • access string
      • does string
      • enabled boolean
        false when the server's feature flag is off
    • wording map<string, object>
      Client-facing texts by language (en, ka, ru)
      Fields: 4
      • connect string
      • invite string
      • button string
      • review string

Start a connection

POST/v1/integrations/{kind}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Google kinds return auth_url (open it in the browser). Cloudflare takes token. invite_email instead creates a single-use link for whoever manages the account (delivered via the integration.invited webhook). cloudflare and google_bp return 403 feature_disabled when their flag is off.

Parameters

ParameterType and description
kindpathRequiredstring

Allowed values: google_bp, gsc, ga4, cloudflare

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • brand_id string Required
  • token string
    Cloudflare API token (Zone > Bot Management > Edit)
  • invite_email string email

Responses

  • 201 Started

    application/json ConnectResult

    • integration Integration
    • auth_url string
      Google consent screen
    • invite_url string
      Single-use link for the person who manages the account
    • note string
  • 400 Error

    application/json Error

  • 403 Error

    application/json Error

Choose the location / site / property (status needs_selection)

PATCH/v1/integrations/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • config map<string, string>

Responses

  • 200 OK

    application/json Integration

    • id string
    • brand_id string
    • kind string

      Allowed values: google_bp, gsc, ga4, cloudflare

    • status string

      Allowed values: invited, pending, connected, needs_selection, error, revoked

    • account string
    • scopes string
    • config map<string, string>
    • invite_email string
    • last_sync_at string date-time
    • last_error string
    • created_at string date-time
    • updated_at string date-time

Disconnect (revokes Google tokens)

DELETE/v1/integrations/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 204 Revoked

Sync an account now

POST/v1/integrations/{id}/sync

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Integration

    • id string
    • brand_id string
    • kind string

      Allowed values: google_bp, gsc, ga4, cloudflare

    • status string

      Allowed values: invited, pending, connected, needs_selection, error, revoked

    • account string
    • scopes string
    • config map<string, string>
    • invite_email string
    • last_sync_at string date-time
    • last_error string
    • created_at string date-time
    • updated_at string date-time
  • 403 Error

    application/json Error

Run a Cloudflare action

POST/v1/integrations/{id}/actions

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

The only action is allow_ai_crawlers (turns off Block AI bots; reversible from the actions log). Requires the cloudflare flag.

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • action string Required

    Allowed values: allow_ai_crawlers

Responses

  • 201 Logged action

    application/json Action

    • id string
    • brand_id string
    • channel string

      Allowed values: site, gbp, gsc, bing, cloudflare, reviews

    • kind string
    • target string
    • summary string
    • content_id string
    • integration_id string
    • before any
      Previous value (when known)
    • after any
      New value
    • status string

      Allowed values: done, failed, rolled_back

    • error string
    • rollback_url string
      POST here to undo (reversible actions only)
    • created_at string date-time
    • rolled_back_at string date-time
  • 400 Error

    application/json Error

  • 403 Error

    application/json Error

Propose Business Profile text from confirmed facts

POST/v1/gbp/profile

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Requires the google_bp flag and a connected Business Profile.

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • brand_id string Required

Responses

  • 201 Proposed

    application/json Content[]

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from
  • 403 Error

    application/json Error

Visits from AI engines (GA4, last 28 days)

GET/v1/ai-traffic

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idqueryRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json TrafficRow[]

    • source string
    • sessions integer
    • from string date
    • to string date

Actions

Every change PromART made, in any channel or account

GET/v1/actions

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
channelquerystring

Allowed values: site, gbp, gsc, bing, cloudflare, reviews

limitqueryinteger

Default: 100At most 1000

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Action[]

    • id string
    • brand_id string
    • channel string

      Allowed values: site, gbp, gsc, bing, cloudflare, reviews

    • kind string
    • target string
    • summary string
    • content_id string
    • integration_id string
    • before any
      Previous value (when known)
    • after any
      New value
    • status string

      Allowed values: done, failed, rolled_back

    • error string
    • rollback_url string
      POST here to undo (reversible actions only)
    • created_at string date-time
    • rolled_back_at string date-time

Undo a reversible action

POST/v1/actions/{id}/rollback

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Action

    • id string
    • brand_id string
    • channel string

      Allowed values: site, gbp, gsc, bing, cloudflare, reviews

    • kind string
    • target string
    • summary string
    • content_id string
    • integration_id string
    • before any
      Previous value (when known)
    • after any
      New value
    • status string

      Allowed values: done, failed, rolled_back

    • error string
    • rollback_url string
      POST here to undo (reversible actions only)
    • created_at string date-time
    • rolled_back_at string date-time
  • 400 Error

    application/json Error

Workspace

Log out (delete the current session)

DELETE/v1/sessions

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 204 Logged out
  • 401 Error

    application/json Error

Current workspace, plan and signing secret

GET/v1/me

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json object

    • workspace Workspace
      Fields: 8
      • id string
      • name string
      • plan string
      • parent_id string
      • auto_publish_technical boolean
        Auto-publish technical changes (needs the API delivery add-on)
      • api_delivery_enabled boolean
        Paid API delivery add-on
      • auto_fixes boolean
        Fixes are written automatically after each diagnosis. Off = analytics only, fixes on request.
      • created_at string date-time
    • plan Plan
      Fields: 16
      • name string
      • price_gel integer
      • prompts integer
      • engines integer
      • brands integer
      • competitors integer
      • languages integer
      • answers_per_month integer
      • interval string
      • daily_prompts integer
      • diagnosis boolean
      • autopilot boolean
      • child_workspaces integer
      • overage string

        Allowed values: block, bill

      • rate_limit_rps number
      • api_access boolean
        API keys may call the API (the panel works on every plan)
    • signing_secret string
      Key for verifying X-Sachino-Signature on content responses
  • 401 Error

    application/json Error

Workspace settings

PATCH/v1/settings

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • auto_publish_technical boolean
    Publish technical fixes (schema, meta) and Cloudflare crawler changes without approval
  • auto_fixes boolean
    Write fixes automatically after every diagnosis (Autopilot plans). Off (default) = analytics only; fixes are written when you call POST /v1/fixes. Turning it on without Autopilot returns 402 plan_limit.

Responses

  • 200 Workspace

    application/json Workspace

    • id string
    • name string
    • plan string
    • parent_id string
    • auto_publish_technical boolean
      Auto-publish technical changes (needs the API delivery add-on)
    • api_delivery_enabled boolean
      Paid API delivery add-on
    • auto_fixes boolean
      Fixes are written automatically after each diagnosis. Off = analytics only, fixes on request.
    • created_at string date-time

Client workspaces under this agency workspace

GET/v1/workspaces

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Workspace[]

    • id string
    • name string
    • plan string
    • parent_id string
    • auto_publish_technical boolean
      Auto-publish technical changes (needs the API delivery add-on)
    • api_delivery_enabled boolean
      Paid API delivery add-on
    • auto_fixes boolean
      Fixes are written automatically after each diagnosis. Off = analytics only, fixes on request.
    • created_at string date-time

Create a client workspace (agency plans)

POST/v1/workspaces

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • name string Required

Responses

  • 201 Created; store the API key now, it is not shown again

    application/json object

    • workspace Workspace
    • api_key string
    • note string
  • 402 Error

    application/json Error

AI engines and how each is reached

GET/v1/engines

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json object[]

    • name string
    • phase string

      Allowed values: mvp, phase2, phase3

    • routes string[]
      Configured routes in order (first = primary, the rest are backups); mock answers are simulated
    • live boolean
      A real provider adapter exists for this engine (chatgpt via openai, gemini via gemini, claude via anthropic). It answers live only when routes puts that provider first

Usage this month against the plan, and add-ons

GET/v1/usage

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Usage

    • plan Plan
    • month string
    • answers integer
    • queued_jobs integer
    • prompts integer
    • brands integer
    • overage_answers integer
    • child_workspaces integer
    • add_ons object[]
      Fields: 4
      • name string
      • title string
      • description string
      • enabled boolean

Catalog

Brands, facts and prompts.

List brands

GET/v1/brands

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Brand[]

    • id string Read-only
    • name string
    • domain string
    • industry string
    • city string
    • variants string[]
      Other spellings (e.g. Georgian, Russian)
    • competitors Competitor[]
    • languages string[]
    • markets string[]
    • engines string[]
    • channel string
      api: your backend calls the PromART API; gbp: Business Profile only

      Allowed values: api, gbp

    • created_at string date-time Read-only

Create a brand

POST/v1/brands

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json Brand

  • name string
  • domain string
  • industry string
  • city string
  • variants string[]
    Other spellings (e.g. Georgian, Russian)
  • competitors Competitor[]
  • languages string[]
  • markets string[]
  • engines string[]
  • channel string
    api: your backend calls the PromART API; gbp: Business Profile only

    Allowed values: api, gbp

Responses

  • 201 Created

    application/json Brand

    • id string Read-only
    • name string
    • domain string
    • industry string
    • city string
    • variants string[]
      Other spellings (e.g. Georgian, Russian)
    • competitors Competitor[]
    • languages string[]
    • markets string[]
    • engines string[]
    • channel string
      api: your backend calls the PromART API; gbp: Business Profile only

      Allowed values: api, gbp

    • created_at string date-time Read-only
  • 400 Error

    application/json Error

  • 402 Error

    application/json Error

Get a brand

GET/v1/brands/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Brand

    • id string Read-only
    • name string
    • domain string
    • industry string
    • city string
    • variants string[]
      Other spellings (e.g. Georgian, Russian)
    • competitors Competitor[]
    • languages string[]
    • markets string[]
    • engines string[]
    • channel string
      api: your backend calls the PromART API; gbp: Business Profile only

      Allowed values: api, gbp

    • created_at string date-time Read-only
  • 404 Error

    application/json Error

Update a brand (fields present in the body overwrite)

PATCH/v1/brands/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json Brand

  • name string
  • domain string
  • industry string
  • city string
  • variants string[]
    Other spellings (e.g. Georgian, Russian)
  • competitors Competitor[]
  • languages string[]
  • markets string[]
  • engines string[]
  • channel string
    api: your backend calls the PromART API; gbp: Business Profile only

    Allowed values: api, gbp

Responses

  • 200 OK

    application/json Brand

    • id string Read-only
    • name string
    • domain string
    • industry string
    • city string
    • variants string[]
      Other spellings (e.g. Georgian, Russian)
    • competitors Competitor[]
    • languages string[]
    • markets string[]
    • engines string[]
    • channel string
      api: your backend calls the PromART API; gbp: Business Profile only

      Allowed values: api, gbp

    • created_at string date-time Read-only
  • 400 Error

    application/json Error

List facts

GET/v1/facts

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
statusquerystring

Allowed values: confirmed, unconfirmed

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Fact[]

    • id string Read-only
    • brand_id string
    • key string
    • value string
    • lang string
      Language code or any
    • url string
    • source string

      Allowed values: api, form, extracted

    • status string

      Allowed values: confirmed, unconfirmed

    • updated_at string date-time Read-only

Add facts (one object or an array)

POST/v1/facts

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Facts are the only source PromART writes from; every generated sentence cites fact IDs.

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json one of

  1. Option 1 Fact

    • brand_id string
    • key string
    • value string
    • lang string
      Language code or any
    • url string
    • source string

      Allowed values: api, form, extracted

    • status string

      Allowed values: confirmed, unconfirmed

  2. Option 2 Fact[]

    • brand_id string
    • key string
    • value string
    • lang string
      Language code or any
    • url string
    • source string

      Allowed values: api, form, extracted

    • status string

      Allowed values: confirmed, unconfirmed

Responses

  • 201 Created

    application/json Fact[]

    • id string Read-only
    • brand_id string
    • key string
    • value string
    • lang string
      Language code or any
    • url string
    • source string

      Allowed values: api, form, extracted

    • status string

      Allowed values: confirmed, unconfirmed

    • updated_at string date-time Read-only
  • 400 Error

    application/json Error

Edit or confirm a fact

PATCH/v1/facts/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

A changed value marks every change that uses the fact stale and queues regeneration.

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • key string
  • value string
  • lang string
  • url string
  • status string

    Allowed values: confirmed

Responses

  • 200 OK

    application/json Fact

    • id string Read-only
    • brand_id string
    • key string
    • value string
    • lang string
      Language code or any
    • url string
    • source string

      Allowed values: api, form, extracted

    • status string

      Allowed values: confirmed, unconfirmed

    • updated_at string date-time Read-only
  • 404 Error

    application/json Error

Delete a fact

DELETE/v1/facts/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 Deleted

    application/json object

    • deleted boolean
  • 404 Error

    application/json Error

Extract unconfirmed facts from a page

POST/v1/facts/extract

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • brand_id string Required
  • url string Required

Responses

  • 201 Extracted (status unconfirmed)

    application/json Fact[]

    • id string Read-only
    • brand_id string
    • key string
    • value string
    • lang string
      Language code or any
    • url string
    • source string

      Allowed values: api, form, extracted

    • status string

      Allowed values: confirmed, unconfirmed

    • updated_at string date-time Read-only

List prompts

GET/v1/prompts

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
activequerystring
Only active prompts

Allowed values: true

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Prompt[]

    • id string Read-only
    • brand_id string
    • text string
    • language string
    • market string
    • target_url string
    • active boolean
    • created_at string date-time Read-only

Add prompts (an array or {"prompts":[...]})

POST/v1/prompts

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json one of

  1. Option 1 Prompt[]

    • brand_id string
    • text string
    • language string
    • market string
    • target_url string
    • active boolean
  2. Option 2 object

    • prompts Prompt[]
      Fields: 6
      • brand_id string
      • text string
      • language string
      • market string
      • target_url string
      • active boolean

Responses

  • 201 Created

    application/json Prompt[]

    • id string Read-only
    • brand_id string
    • text string
    • language string
    • market string
    • target_url string
    • active boolean
    • created_at string date-time Read-only
  • 400 Error

    application/json Error

  • 402 Error

    application/json Error

Update a prompt

PATCH/v1/prompts/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • active boolean
  • target_url string
  • text string

Responses

  • 200 OK

    application/json Prompt

    • id string Read-only
    • brand_id string
    • text string
    • language string
    • market string
    • target_url string
    • active boolean
    • created_at string date-time Read-only

Delete a prompt

DELETE/v1/prompts/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 Deleted

    application/json object

    • deleted boolean

Suggest prompts for a brand (not saved)

POST/v1/prompts/suggest

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • brand_id string Required
  • per_language integer

Responses

  • 200 OK

    application/json Prompt[]

    • id string Read-only
    • brand_id string
    • text string
    • language string
    • market string
    • target_url string
    • active boolean
    • created_at string date-time Read-only

Measurement

List runs

GET/v1/runs

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
limitqueryinteger

Default: 50At most 500

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Run[]

    • id string
    • brand_id string
    • kind string

      Allowed values: baseline, scheduled, daily, manual, remeasure

    • status string
    • repeats integer
    • engines string[]
    • jobs_total integer
    • jobs_done integer
    • jobs_failed integer
    • created_at string date-time
    • finished_at string date-time

Start a measurement run

POST/v1/runs

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Expands prompt × engine × (language, location) × repeats into queued jobs.

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • brand_id string Required
  • engines string[]
  • repeats integer
  • prompt_ids string[]
    Optional subset

Responses

  • 201 Created

    application/json Run

    • id string
    • brand_id string
    • kind string

      Allowed values: baseline, scheduled, daily, manual, remeasure

    • status string
    • repeats integer
    • engines string[]
    • jobs_total integer
    • jobs_done integer
    • jobs_failed integer
    • created_at string date-time
    • finished_at string date-time
  • 402 Error

    application/json Error

Get a run

GET/v1/runs/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Run

    • id string
    • brand_id string
    • kind string

      Allowed values: baseline, scheduled, daily, manual, remeasure

    • status string
    • repeats integer
    • engines string[]
    • jobs_total integer
    • jobs_done integer
    • jobs_failed integer
    • created_at string date-time
    • finished_at string date-time
  • 404 Error

    application/json Error

Answers viewer (filterable, newest first)

GET/v1/answers

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Inclusive
run_idquerystring
prompt_idquerystring
mentionedquerystring
Only answers that do / do not name the client

Allowed values: yes, no

qquerystring
Case-insensitive text search in the answer
limitqueryinteger

Default: 50At most 500

offsetqueryinteger

Default: 0

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json object

    • items Answer[]
      Fields: 13
      • id string
      • run_id string
      • prompt_id string
      • prompt string
      • engine string
      • language string
      • location string
      • route string
      • text string
      • citations string[]
      • screenshot_url string
        Reserved: no engine adapter captures screenshots yet, so answers leave this field out
      • mentions object[]
        Fields: 5
        • name string
        • is_client boolean
        • position integer
          1 = named first
        • sentiment number

          From −1 to 1

        • cited_urls string[]
      • created_at string date-time
    • total integer

Visibility by week, engine and language

GET/v1/visibility

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Inclusive
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json object

    • overall VisRow
      Fields: 8
      • week string
      • engine string
      • language string
      • answers integer
      • mentioned integer
      • visibility_pct number
      • avg_position number
      • avg_sentiment number
    • rows VisRow[]
      Fields: 8
      • week string
      • engine string
      • language string
      • answers integer
      • mentioned integer
      • visibility_pct number
      • avg_position number
      • avg_sentiment number

Share of voice against competitors

GET/v1/share-of-voice

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Inclusive
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json SOVRow[]

    • name string
    • is_client boolean
    • mentions integer
    • share_pct number
    • avg_position number
    • avg_sentiment number

Domains AI engines cite

GET/v1/citations

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Inclusive
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json CitationRow[]

    • domain string
    • count integer
    • share_pct number
    • owner string

      Allowed values: client, competitor, third_party

Recent alerts

GET/v1/alerts

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json object[]

    • id string
    • brand_id string
    • engine string
    • message string
    • created_at string date-time

Weekly report for a brand

GET/v1/report

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idqueryRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Report

    • brand Brand
    • period string
      from – to as text
    • from string date
      First day of the report week
    • to string date
      Last day of the report week (today, UTC)
    • visibility_pct number
    • visibility_prev_pct number
    • delta_pp number
    • by_engine VisRow[]
    • share_of_voice SOVRow[]
    • top_citations CitationRow[]
    • live_changes integer
    • pending_approval integer
    • experiments Experiment[]
    • recommendations Recommendation[]
    • alerts string[]
    • ai_traffic TrafficRow[]
    • recent_actions Action[]
    • failing_site_checks SiteCheck[]
  • 404 Error

    application/json Error

Fixes

Diagnosis, generated changes, approval, experiments.

Diagnose a brand (site checks, gaps, page and block recommendations)

POST/v1/diagnose

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • brand_id string Required

Responses

  • 200 OK

    application/json Recommendation[]

    • id string
    • brand_id string
    • kind string
    • auto_fixable boolean
    • priority integer
      1 = highest
    • title string
    • detail string
    • url string
    • created_at string date-time
  • 402 Error

    application/json Error

Current recommendations

GET/v1/recommendations

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
auto_fixablequerystring

Allowed values: true, false

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Recommendation[]

    • id string
    • brand_id string
    • kind string
    • auto_fixable boolean
    • priority integer
      1 = highest
    • title string
    • detail string
    • url string
    • created_at string date-time

Generate fact-checked changes for a page

POST/v1/content/generate

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • brand_id string Required
  • url string Required
  • language string
  • kinds string[]
    Default all; block generates section blocks

    Allowed values: answer_block, faq, meta_description, schema, block

Responses

  • 201 Proposed changes

    application/json Content[]

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from
  • 400 Error

    application/json Error

List changes with placement instructions and source facts

GET/v1/content/items

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
statusquerystring
One status or a comma list, e.g. approved,live (see ContentStatus)
urlquerystring
kindquerystring
A kind (answer_block, faq, meta_description, schema, page, gbp_profile, gbp_post, block:<id>), or block for every block
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Content[]

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from

Get a change

GET/v1/content/items/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from
  • 404 Error

    application/json Error

Approve a change (optionally edited)

POST/v1/content/{id}/approve

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Without the API delivery add-on, site changes become approved (ready to apply by hand, with placement; content.approved) and wait for POST /v1/content/{id}/applied. With the add-on they go live right away (served by GET /v1/content, content.published, IndexNow, experiment). Pages always become approved and wait for POST /v1/pages/{id}/published. Business Profile changes (gbp_profile, gbp_post) are written to Google automatically on every plan (feature flag google_bp). Edited bodies are re-sanitized.

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body

application/json object

  • Shape depends on the content kind.
    Fields: 8
    • text string
      answer_block, meta_description
    • sentences Sentence[]
    • faq object[]
      Fields: 3
      • q string
      • a string
      • fact_ids string[]
    • schema object
      JSON-LD
    • block Block
    • page Page
    • profile object
      gbp_profile
      Fields: 4
      • description string

        Up to 750 characters

      • phone string
      • website string
      • hours string
        schema.org openingHours, e.g. Mo-Sa 09:00-20:00, Su 10:00-16:00
    • post object
      gbp_post
      Fields: 2
      • summary string
      • url string

Responses

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from
  • 400 Error

    application/json Error

  • 403 Error

    application/json Error

Reject a proposed, blocked or approved (not yet applied) change

POST/v1/content/{id}/reject

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from
  • 400 Error

    application/json Error

Roll back a live change

POST/v1/content/{id}/rollback

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Changes delivered through the API or to Business Profile are removed by PromART (rolled_back). Changes the client applied by hand become remove_requested (content.removal_requested) until POST /v1/content/{id}/removed.

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from
  • 400 Error

    application/json Error

Mark an approved change as applied by hand

POST/v1/content/{id}/applied

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

The client pasted the change into the site. It becomes live (delivery: manual), content.published fires, the URL is submitted to IndexNow and an experiment opens (re-measure, keep or roll back). New pages use POST /v1/pages/{id}/published instead.

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from
  • 400 Error

    application/json Error

  • 404 Error

    application/json Error

Confirm a change was removed from the site

POST/v1/content/{id}/removed

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

For changes in remove_requested. The change becomes rolled_back, content.rolled_back fires and the URL is submitted to IndexNow.

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      Page URL, or gbp://<domain> for Business Profile changes
    • kind string
      answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

      Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      How a live change reached the client

      Allowed values: api, manual, gbp

    • variant integer
    • verifier_notes string
      Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Confirmed facts the change is written from
  • 400 Error

    application/json Error

  • 404 Error

    application/json Error

Before/after experiments for live changes

GET/v1/experiments

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idquerystring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Experiment[]

    • id string
    • brand_id string
    • content_id string
    • url string
    • prompt_ids string[]
    • baseline number
    • baseline_n integer
    • after number
    • after_n integer
    • lift_pp number
    • status string

      Allowed values: waiting, measuring, kept, rolled_back, inconclusive, cancelled

    • run_id string
    • pickup_at string date-time
    • created_at string date-time
    • decided_at string date-time

Re-measure an experiment now

POST/v1/experiments/{id}/measure-now

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 Queued

    application/json object

    • queued boolean

Webhooks

List webhooks

GET/v1/webhooks

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Webhook[]

    • id string
    • url string
    • events EventType[]

      Allowed values: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

    • secret string
      Returned on creation; signs deliveries
    • created_at string date-time

Subscribe a URL to events

POST/v1/webhooks

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • url string uri Required
  • events EventType[] Required

    Allowed values: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

Responses

  • 201 Created (secret shown here)

    application/json Webhook

    • id string
    • url string
    • events EventType[]

      Allowed values: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

    • secret string
      Returned on creation; signs deliveries
    • created_at string date-time
  • 400 Error

    application/json Error

Delete a webhook

DELETE/v1/webhooks/{id}

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 Deleted

    application/json object

    • deleted boolean

Recent events (same bodies as webhook deliveries)

GET/v1/events

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
limitqueryinteger

Default: 100At most 1000

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json object[]

    • id string
    • Allowed values: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

    • payload object
      {id, type, created_at, data}
    • created_at string date-time

Reviews

List customer contacts

GET/v1/contacts

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idqueryRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json Contact[]

    • id string Read-only
    • brand_id string
    • name string
    • phone string
    • email string
    • language string
    • source string

      Allowed values: csv, api, crm

    • opted_out boolean
    • last_requested_at string date-time
    • created_at string date-time

Add contacts (customers who agreed to be contacted)

POST/v1/contacts

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • brand_id string Required
  • consent boolean Required
    Must be true
  • contacts Contact[] Required
    Fields: 9
    • brand_id string
    • name string
    • phone string
    • email string
    • language string
    • source string

      Allowed values: csv, api, crm

    • opted_out boolean
    • last_requested_at string date-time
    • created_at string date-time

Responses

  • 201 Added

    application/json object

    • added integer
  • 400 Error

    application/json Error

Import contacts from CSV

POST/v1/contacts/import

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Columns Name, Phone, Email, Language (header row; UTF-8, BOM allowed). Duplicates are skipped.

Parameters

ParameterType and description
brand_idqueryRequiredstring
consentqueryRequiredstring

Allowed values: true

langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

text/csv string

Responses

  • 201 Imported

    application/json object

    • rows integer
    • added integer
  • 400 Error

    application/json Error

Opt a contact out of review requests

POST/v1/contacts/{id}/opt-out

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 204 Opted out

Review request settings

GET/v1/reviews/settings

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idqueryRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 OK

    application/json ReviewSettings

    • auto boolean
      Send daily to new contacts
    • review_url string
      Defaults to the Business Profile review link
    • daily_max integer

      Default: 50

Update review request settings

PUT/v1/reviews/settings

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Parameters

ParameterType and description
brand_idqueryRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json ReviewSettings

  • auto boolean
    Send daily to new contacts
  • review_url string
    Defaults to the Business Profile review link
  • daily_max integer

    Default: 50

Responses

  • 200 OK

    application/json ReviewSettings

    • auto boolean
      Send daily to new contacts
    • review_url string
      Defaults to the Business Profile review link
    • daily_max integer

      Default: 50

Ask eligible customers for a review

POST/v1/review-requests

Auth: Bearer token, an API key (sk_live_…) or a panel session (sess_…)

Not opted out and not asked in the last 180 days. Each request is delivered as a review.request webhook to your messaging system; dry_run only returns the messages.

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • brand_id string Required
  • max integer
  • dry_run boolean

Responses

  • 200 Requests

    application/json object[]

    • contact_id string
    • name string
    • phone string
    • email string
    • language string
    • message string
  • 400 Error

    application/json Error

Public

No API key. OAuth return, invite pages and their fonts, signup, panel login, docs.

Health check

GET/healthz

No auth

Responses

  • 200 OK

    application/json object

    • status string

      Allowed values: ok

This OpenAPI document

GET/openapi.yaml

No auth

Responses

  • 200 OpenAPI 3.1 YAML

    application/yaml string

Rendered API docs (this page)

GET/docs

No auth

This reference as one HTML page, rendered on the server from this document and complete without JavaScript: the guide, then every endpoint with its parameters, bodies, responses, code samples and examples. Its interface and the texts of this document are in the request language (lang, else Accept-Language, else English); a text without a translation is shown in English.

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 HTML

    Headers

    • Content-Language string
      Language of the texts in this response: the lang parameter, else the best supported Accept-Language, else en (always en for /openapi.yaml)

    text/html string

  • 304 Not modified (If-None-Match)

Stylesheet, script and fonts of the docs page

GET/docs/assets/{file}

No auth

docs.css, docs.js and the web fonts the page uses: Sachino Sans (FiraGO subsets, license OFL-FiraGO.txt) in weights 400, 500 and 600 for Latin, Georgian and Cyrillic, and Fira Code (OFL-FiraCode.txt). The page links each file with a ?v= content hash; with the current hash a file is cached for a year (immutable).

Parameters

ParameterType and description
filepathRequiredstring

Example: docs.css

vquerystring
Content hash of the file, as the page links it

Responses

  • 200 The file (text/css, text/javascript, font/woff2 or text/plain for a license)

    text/css string

  • 304 Not modified (If-None-Match)
  • 404 No such file

Web fonts of the invite page

GET/assets/fonts/{file}

No auth

Sachino Sans (FiraGO subsets, SIL Open Font License; the license is OFL.txt) in weights 400 and 600 for Latin, Georgian and Cyrillic, e.g. sachino-sans-400-georgian.woff2. Cached for a year (immutable); pages link them with a ?v= content hash.

Parameters

ParameterType and description
filepathRequiredstring

Example: sachino-sans-400-latin.woff2

Responses

  • 200 The file (font/woff2, or text/plain for the license)

    font/woff2 string binary

  • 304 Not modified (If-None-Match)
  • 404 No such file

Web fonts of the invite page (under /connect/)

GET/connect/assets/fonts/{file}

No auth

Sachino Sans (FiraGO subsets, SIL Open Font License; the license is OFL.txt) in weights 400 and 600 for Latin, Georgian and Cyrillic, e.g. sachino-sans-400-georgian.woff2. Cached for a year (immutable); pages link them with a ?v= content hash. The invite page links this copy, under the /connect/ prefix that proxies send to the API; the files are the same as under /assets/fonts/.

Parameters

ParameterType and description
filepathRequiredstring

Example: sachino-sans-400-latin.woff2

Responses

  • 200 The file (font/woff2, or text/plain for the license)

    font/woff2 string binary

  • 304 Not modified (If-None-Match)
  • 404 No such file

Create a free-audit workspace

POST/v1/signup

No auth

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • name string Required

Responses

  • 201 Created; store the API key now, it is not shown again

    application/json object

    • workspace Workspace
    • api_key string
    • note string
  • 400 Error

    application/json Error

Log in to the panel (API key → session token)

POST/v1/sessions

No auth

Exchanges a workspace API key for a sess_… panel session token valid 30 days. Sessions work on every plan.

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • api_key string Required

Responses

  • 201 Session created

    application/json object

    • token string
    • workspace Workspace
      Fields: 8
      • id string
      • name string
      • plan string
      • parent_id string
      • auto_publish_technical boolean
        Auto-publish technical changes (needs the API delivery add-on)
      • api_delivery_enabled boolean
        Paid API delivery add-on
      • auto_fixes boolean
        Fixes are written automatically after each diagnosis. Off = analytics only, fixes on request.
      • created_at string date-time
  • 400 Error

    application/json Error

  • 401 Error

    application/json Error

Plans and limits

GET/v1/plans

No auth

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 Plans keyed by name

    application/json map<string, Plan>

    • name string
    • price_gel integer
    • prompts integer
    • engines integer
    • brands integer
    • competitors integer
    • languages integer
    • answers_per_month integer
    • interval string
    • daily_prompts integer
    • diagnosis boolean
    • autopilot boolean
    • child_workspaces integer
    • overage string

      Allowed values: block, bill

    • rate_limit_rps number
    • api_access boolean
      API keys may call the API (the panel works on every plan)

Google OAuth return URL

GET/v1/oauth/google/callback

No auth

Google redirects here after consent. PromART exchanges the code, discovers the matching location/site/property and redirects the browser to the panel (/#/integrations?kind=&status=).

Parameters

ParameterType and description
codequerystring
statequeryRequiredstring
HMAC-signed, 30 minutes
errorquerystring

Responses

  • 302 Redirect to the panel

Invite page for the person who manages the account

GET/connect/{token}

No auth

HTML page with a Google button or a Cloudflare token form, in the request language (lang, else Accept-Language, else English) with links to the page in the other two. The connect text is the wording of GET /v1/integrations.

Parameters

ParameterType and description
tokenpathRequiredstring
Single-use invite token (14 days)
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 200 HTML

    text/html string

  • 404 Invalid, used or expired link (HTML)

Connect Cloudflare from an invite

POST/connect/{token}

No auth

Parameters

ParameterType and description
tokenpathRequiredstring
Single-use invite token (14 days)
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/x-www-form-urlencoded object

  • token string Required
    Cloudflare API token

Responses

  • 200 Connected (HTML)
  • 400 Error (HTML): the form again with the reason, or the expired-link page

Start Google consent from an invite

GET/connect/{token}/google

No auth

Parameters

ParameterType and description
tokenpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Responses

  • 302 Redirect to Google consent
  • 400 Error (HTML)

Admin

Operator endpoints, X-Admin-Token.

Create a workspace on any plan

POST/v1/admin/workspaces

Auth: the operator token in the X-Admin-Token header

Parameters

ParameterType and description
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • name string Required
  • plan string

    Default: optimize

  • parent_id string

Responses

  • 201 Created; store the API key now, it is not shown again

    application/json object

    • workspace Workspace
    • api_key string
    • note string
  • 401 Error

    application/json Error

Change a workspace's plan or the API delivery add-on

PATCH/v1/admin/workspaces/{id}

Auth: the operator token in the X-Admin-Token header

Parameters

ParameterType and description
idpathRequiredstring
langqueryAccept-Languageheader
Language of the texts in the response: ka, ru or en. See Language

Request body Required

application/json object

  • plan string
  • api_delivery_enabled boolean
    Switch the paid API delivery add-on

Responses

  • 200 Workspace

    application/json Workspace

    • id string
    • name string
    • plan string
    • parent_id string
    • auto_publish_technical boolean
      Auto-publish technical changes (needs the API delivery add-on)
    • api_delivery_enabled boolean
      Paid API delivery add-on
    • auto_fixes boolean
      Fixes are written automatically after each diagnosis. Off = analytics only, fixes on request.
    • created_at string date-time
  • 401 Error

    application/json Error

  • 404 Error

    application/json Error

Schemas

The objects the endpoints take and return, each described once. Endpoints show the fields of their own body and response and link here for the rest.

Error object

  • error object
    Fields: 4
    • code string

      Allowed values: unauthorized, plan_limit, api_access_required, addon_required, feature_disabled, not_found, invalid_request, invalid_json, rate_limited, internal

    • message string
      Human-readable; in the response language when reason is set, else English
    • reason string
      Specific cause: the stable key of the message, e.g. http.err.brand_id_required or core.err.not_found.brand (only on errors that have one)
    • params object
      The values in the message, unformatted; a plan, status or engine is its code (only with reason, and only when there are any)

Workspace object

  • id string
  • name string
  • plan string
  • parent_id string
  • auto_publish_technical boolean
    Auto-publish technical changes (needs the API delivery add-on)
  • api_delivery_enabled boolean
    Paid API delivery add-on
  • auto_fixes boolean
    Fixes are written automatically after each diagnosis. Off = analytics only, fixes on request.
  • created_at string date-time

Plan object

  • name string
  • price_gel integer
  • prompts integer
  • engines integer
  • brands integer
  • competitors integer
  • languages integer
  • answers_per_month integer
  • interval string
  • daily_prompts integer
  • diagnosis boolean
  • autopilot boolean
  • child_workspaces integer
  • overage string

    Allowed values: block, bill

  • rate_limit_rps number
  • api_access boolean
    API keys may call the API (the panel works on every plan)

Usage object

  • plan Plan
  • month string
  • answers integer
  • queued_jobs integer
  • prompts integer
  • brands integer
  • overage_answers integer
  • child_workspaces integer
  • add_ons object[]
    Fields: 4
    • name string
    • title string
    • description string
    • enabled boolean

Competitor object

  • name string
  • variants string[]
  • domain string

Brand object

  • id string Read-only
  • name string
  • domain string
  • industry string
  • city string
  • variants string[]
    Other spellings (e.g. Georgian, Russian)
  • competitors Competitor[]
  • languages string[]
  • markets string[]
  • engines string[]
  • channel string
    api: your backend calls the PromART API; gbp: Business Profile only

    Allowed values: api, gbp

  • created_at string date-time Read-only

Fact object

  • id string Read-only
  • brand_id string
  • key string
  • value string
  • lang string
    Language code or any
  • url string
  • source string

    Allowed values: api, form, extracted

  • status string

    Allowed values: confirmed, unconfirmed

  • updated_at string date-time Read-only

Prompt object

  • id string Read-only
  • brand_id string
  • text string
  • language string
  • market string
  • target_url string
  • active boolean
  • created_at string date-time Read-only

Run object

  • id string
  • brand_id string
  • kind string

    Allowed values: baseline, scheduled, daily, manual, remeasure

  • status string
  • repeats integer
  • engines string[]
  • jobs_total integer
  • jobs_done integer
  • jobs_failed integer
  • created_at string date-time
  • finished_at string date-time

Answer object

  • id string
  • run_id string
  • prompt_id string
  • prompt string
  • engine string
  • language string
  • location string
  • route string
  • text string
  • citations string[]
  • screenshot_url string
    Reserved: no engine adapter captures screenshots yet, so answers leave this field out
  • mentions object[]
    Fields: 5
    • name string
    • is_client boolean
    • position integer
      1 = named first
    • sentiment number

      From −1 to 1

    • cited_urls string[]
  • created_at string date-time

VisRow object

  • week string
  • engine string
  • language string
  • answers integer
  • mentioned integer
  • visibility_pct number
  • avg_position number
  • avg_sentiment number

SOVRow object

  • name string
  • is_client boolean
  • mentions integer
  • share_pct number
  • avg_position number
  • avg_sentiment number

CitationRow object

  • domain string
  • count integer
  • share_pct number
  • owner string

    Allowed values: client, competitor, third_party

Recommendation object

  • id string
  • brand_id string
  • kind string
  • auto_fixable boolean
  • priority integer
    1 = highest
  • title string
  • detail string
  • url string
  • created_at string date-time

Experiment object

  • id string
  • brand_id string
  • content_id string
  • url string
  • prompt_ids string[]
  • baseline number
  • baseline_n integer
  • after number
  • after_n integer
  • lift_pp number
  • status string

    Allowed values: waiting, measuring, kept, rolled_back, inconclusive, cancelled

  • run_id string
  • pickup_at string date-time
  • created_at string date-time
  • decided_at string date-time

TrafficRow object

  • source string
  • sessions integer
  • from string date
  • to string date

Report object

  • brand Brand
  • period string
    from – to as text
  • from string date
    First day of the report week
  • to string date
    Last day of the report week (today, UTC)
  • visibility_pct number
  • visibility_prev_pct number
  • delta_pp number
  • by_engine VisRow[]
  • share_of_voice SOVRow[]
  • top_citations CitationRow[]
  • live_changes integer
  • pending_approval integer
  • experiments Experiment[]
  • recommendations Recommendation[]
  • alerts string[]
  • ai_traffic TrafficRow[]
  • recent_actions Action[]
  • failing_site_checks SiteCheck[]

ContentStatus string

approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

Sentence object

  • text string
  • fact_ids string[]

Block object

  • block_id string
  • selector string
    CSS selector; apply to the first match
  • action string

    Allowed values: replace, append, prepend, before, after

  • html string
    Sanitized HTML

Page object

  • url string
    Suggested URL; replaced by the real one after POST /v1/pages/{id}/published
  • title string
  • language string
  • topic string
  • sections object[]
    Fields: 3
    • heading string
    • html string
      Sanitized HTML (paragraphs, lists, tables)
    • sentences Sentence[]
  • schema object
    JSON-LD to embed in a script type=application/ld+json
  • internal_links object[]
    Fields: 2
    • url string
    • text string

ContentBody object

Shape depends on the content kind.
  • text string
    answer_block, meta_description
  • sentences Sentence[]
  • faq object[]
    Fields: 3
    • q string
    • a string
    • fact_ids string[]
  • schema object
    JSON-LD
  • block Block
  • page Page
  • profile object
    gbp_profile
    Fields: 4
    • description string

      Up to 750 characters

    • phone string
    • website string
    • hours string
      schema.org openingHours, e.g. Mo-Sa 09:00-20:00, Su 10:00-16:00
  • post object
    gbp_post
    Fields: 2
    • summary string
    • url string

Content object

  • id string
  • brand_id string
  • url string
    Page URL, or gbp://<domain> for Business Profile changes
  • kind string
    answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
  • fact_ids string[]
  • technical boolean
  • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

    Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

  • delivery string
    How a live change reached the client

    Allowed values: api, manual, gbp

  • variant integer
  • verifier_notes string
    Why the checks blocked the change (or that it was edited before approval), in the response language (see Language). In English: "sanitizer: <reason>", "verifier: <JSON list of reasons>" or "edited by client before approval".
  • created_at string date-time
  • published_at string date-time
  • updated_at string date-time
  • placement Placement
  • facts FactRef[]
    Confirmed facts the change is written from

Placement object

Where and how to apply a change by hand. where, steps and part labels are in the response language (see Language); part values are the site content itself and are never translated.
  • url string
  • where string
  • steps string[]
  • current string
    Text being replaced, as PromART last read it (replace blocks)
  • parts CopyPart[]

CopyPart object

  • label string
  • format string

    Allowed values: text, html, json-ld, head-html

  • value string

FactRef object

  • id string
  • key string
  • value string
  • lang string

KPI object

  • answers integer
  • mentioned integer
  • visibility_pct number
  • sov_pct number
  • avg_position number
    Lower is better
  • avg_sentiment number

    From −1 to 1

Overview object

  • from string date
  • to string date
  • prev_from string date
  • prev_to string date
  • current KPI
  • previous KPI

TrendRow object

  • week string date
    Monday of the week
  • key string
    Engine, language, brand name, or all
  • is_client boolean
  • answers integer
  • mentioned integer
  • visibility_pct number
  • sov_pct number
  • avg_position number
  • avg_sentiment number

CompetitorRow object

  • name string
  • is_client boolean
  • mentions integer
  • visibility_pct number
  • sov_pct number
  • avg_position number
  • avg_sentiment number
  • prev_visibility_pct number
  • prev_sov_pct number

SourceRow object

  • url string
    Only with by=url
  • domain string
  • owner string

    Allowed values: client, competitor, third_party

  • count integer
    Answers citing it
  • share_pct number
  • engines map<string, integer>

EngineCell object

  • answers integer
  • visibility_pct number
  • avg_position number

PromptRow object

  • prompt_id string
  • text string
  • language string
  • target_url string
  • answers integer
  • visibility_pct number
  • avg_position number
  • top_competitor string
  • engines map<string, EngineCell>

BlockItem object

  • content_id string
  • block_id string
  • selector string
  • action string

    Allowed values: replace, append, prepend, before, after

  • html string
  • fact_ids string[]
  • approved = ready to apply by hand; remove_requested = rolled back, waiting for the client to remove it

    Allowed values: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

Delivery object

  • url string
  • version integer
    Increases with every published change for this URL
  • meta_description string
  • answer_block string
  • faq object[]
    Fields: 3
    • q string
    • a string
    • fact_ids string[]
  • schema object
    JSON-LD
  • blocks BlockItem[]
  • content_ids string[]
  • signature string
    Legacy: HMAC of the body without this field. Verify the X-Sachino-Signature header instead.

SiteCheck object

  • id string
  • check string

    Allowed values: robots_ai_bots, cdn_ai_bots, sitemap, indexnow_key, fetch, noindex, js_rendering, speed, google_index

  • target string
    Domain or URL
  • status string

    Allowed values: ok, warn, fail, unknown

  • detail string
  • instruction string
    Exact task for the client or developer
  • fix string
    Automatic fix PromART can run, e.g. cloudflare:allow_ai_crawlers
  • source string

    Allowed values: crawl, gsc, cloudflare

  • checked_at string date-time

IndexNowInfo object

  • key string
  • files object[]
    Fields: 5
    • brand_id string
    • domain string
    • url string
      https://<domain>/<key>.txt
    • content string
      Exact file body (the key)
    • status string
      From the last site check

      Allowed values: ok, fail, unknown

  • instructions string[]

Integration object

  • id string
  • brand_id string
  • kind string

    Allowed values: google_bp, gsc, ga4, cloudflare

  • status string

    Allowed values: invited, pending, connected, needs_selection, error, revoked

  • account string
  • scopes string
  • config map<string, string>
  • invite_email string
  • last_sync_at string date-time
  • last_error string
  • created_at string date-time
  • updated_at string date-time

IntegrationKind object

  • scope string
    Google OAuth scope
  • access string
  • does string
  • enabled boolean
    false when the server's feature flag is off

ConnectResult object

  • integration Integration
  • auth_url string
    Google consent screen
  • invite_url string
    Single-use link for the person who manages the account
  • note string

Action object

  • id string
  • brand_id string
  • channel string

    Allowed values: site, gbp, gsc, bing, cloudflare, reviews

  • kind string
  • target string
  • summary string
  • content_id string
  • integration_id string
  • before any
    Previous value (when known)
  • after any
    New value
  • status string

    Allowed values: done, failed, rolled_back

  • error string
  • rollback_url string
    POST here to undo (reversible actions only)
  • created_at string date-time
  • rolled_back_at string date-time

Contact object

  • id string Read-only
  • brand_id string
  • name string
  • phone string
  • email string
  • language string
  • source string

    Allowed values: csv, api, crm

  • opted_out boolean
  • last_requested_at string date-time
  • created_at string date-time

ReviewSettings object

  • auto boolean
    Send daily to new contacts
  • review_url string
    Defaults to the Business Profile review link
  • daily_max integer

    Default: 50

EventType string

Allowed values: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

Webhook object

  • id string
  • url string
  • events EventType[]

    Allowed values: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

  • secret string
    Returned on creation; signs deliveries
  • created_at string date-time