Public API overview

The Grona Public API v1 lets your backend run website campaigns from your own product. You can create a campaign, open it in the Grona visual editor, preview it, set it live and check that the Grona snippet is installed, all over HTTPS. The API also returns grants for the Grona mobile SDKs. Use it when campaigns should start in your systems rather than in the Grona dashboard.

Base URL

Every request goes to https://api.grona.ai, and every path starts with /v1:

https://api.grona.ai/v1/campaigns

Request bodies are JSON, sent with Content-Type: application/json. The version in the path changes only for breaking changes, as described in Versioning and deprecation.

Server to server only

Every call carries your workspace secret key, either as Authorization: Bearer grona_sk_<keyId>_<secret> or as X-API-Key: grona_sk_<keyId>_<secret>. The key decides which workspace the call acts on, so the workspace never appears in a URL or a request body.

Call the API from your servers only. A secret key in a browser page or a mobile app can be read by anyone who opens it. Authentication covers how to get a key and how to keep it safe.

The response envelope

Every Public API response uses the same envelope, except that a 429 or 503 body may not. A successful call returns data and meta:

{
  "data": { "id": "671a3c90e4b0a1f2c3d40011", "status": "paused" },
  "meta": { "workspaceId": "65e8a1c47d2f9b03e6a15c42" }
}

meta.workspaceId is the workspace resolved from your key. List responses add meta.count. A failed call returns error with a stable code and a human-readable message:

{
  "error": {
    "code": "conflict",
    "message": "externalId `CMP-1024` is already used by another campaign."
  }
}

Branch on error.code and the HTTP status, never on the message. Errors lists every code and how to fix it.

Resources

Resource	Endpoints	What you do with it
Campaigns	Create, list, get, update, set status, delete	Create website campaigns, A/B tests and multi-page campaigns, then set them live or pause them.
Editor links	Create a link, check a link	Open a variation in the Grona visual editor from your product.
Websites	Verify script	Check that the Grona snippet is on a page.
Mobile grants	Fetch grants	Fetch signed grants for a shopper and hand them to your app.

The endpoint reference has every field, status code and a code sample for each operation. It also lists the endpoints the Grona Android and iOS SDKs call. Your code does not call those.

The same reference is available as an OpenAPI 3.1 file for code generation and API clients: grona-api.yaml.

The API has no endpoint for campaign results. You read results in the Grona dashboard.

A quick tour

Three calls take a campaign from nothing to live: check the snippet, create the campaign, then set it live once you have edited and previewed it. The quickstart runs each call with curl and shows its response.

Quickstart: Public APICheck the snippet, create a campaign, open the editor and set it live.

Next steps

Create campaigns from your platformThe end-to-end flow, from snippet check to live campaign.

AuthenticationGet a secret key, send it and keep it safe.

ConventionsExternal ids, timestamps, pagination and safe retries.

ErrorsEvery error code, and which requests are safe to retry.