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:
proposed → POST /v1/content/{id}/approve → approved (ready to apply).
- 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.
- 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:
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.