Skip to content

AI and insights

18 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.

MCP server (JSON-RPC 2.0): initialize, tools/list, tools/call

POST/mcp

Authenticate with an API key. Read-only tools list_checkouts, get_funnel, list_orders, get_order, get_mrr and list_findings call the same services as the REST endpoints under the same permissions; each call is audited as mcp.tool_called. The merchant must turn MCP on in AI settings. Rate limited per credential and per IP like /v1.

Authentication
API key (Bearer)
Permission
Not stated
Idempotency-Key
Not used
Success
200

Request body · application/jsonrequired

  • jsonrpcstringrequired
    Always2.0
  • idstring
  • methodstringrequired
    One ofinitializepingtools/listtools/call
  • paramsmap<string, any>

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/mcp" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "method": "initialize"
}'
// JSON object. The OpenAPI document does not list its fields.

Run the AI analyst now for this merchant

POST/v1/ai/analyst/run

The weekly schedule does the same for every merchant with the analyst on. Idempotent per period: a query that already has a finding makes no model call. Returns counts of created, existing and discarded findings.

Authentication
API key (Bearer)
Permission
ai:manage
Idempotency-Key
Required
Success
200

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/ai/analyst/run" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-run-v1"
// JSON object. The OpenAPI document does not list its fields.

Whether the signed-in member gets the weekly AI digest email

GET/v1/ai/digest

A per-member setting, off until the member turns it on. Needs ai:read and a member session; API keys have no member and get 403.

Authentication
API key (Bearer)
Permission
ai:read
Idempotency-Key
Not used
Success
200

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/ai/digest" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Opt the signed-in member in or out of the weekly AI digest email

PUT/v1/ai/digest

After the weekly analyst run, opted-in members receive one email with the top open findings; idempotent per merchant, member and week. The change is audited (ai.digest_preference_updated). Needs ai:read and a member session.

Authentication
API key (Bearer)
Permission
ai:read
Idempotency-Key
Required
Success
200

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • enabledbooleanrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X PUT "$GIEP_API_URL/v1/ai/digest" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-digest-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'
// JSON object. The OpenAPI document does not list its fields.

AI analyst findings (suggestions) with the evidence behind each

GET/v1/ai/findings

Each finding carries the query name, parameters, the result snapshot the model saw, its text, severity, suggested action and a link into the workspace. Sorted by severity, newest first.

Authentication
API key (Bearer)
Permission
ai:read
Idempotency-Key
Not used
Success
200

Query parameters

  • statusstring
    One ofopendismisseddone
  • limitinteger
    min 1 · max 200

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/ai/findings" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Dismiss a finding, mark it done, or reopen it

PATCH/v1/ai/findings/{id}

Audited (ai.finding_dismissed, ai.finding_done, ai.finding_reopened). Needs ai:manage.

Authentication
API key (Bearer)
Permission
ai:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • statusstringrequired
    One ofopendismisseddone

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X PATCH "$GIEP_API_URL/v1/ai/findings/6d1e65ac-7d19-48d4-abb7-e70023aa" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-findings-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "open"
}'
// JSON object. The OpenAPI document does not list its fields.

AI feature switches for the merchant (analyst, editor, MCP)

GET/v1/ai/settings

All three features are off until the merchant turns them on. Needs ai:read. The model is a deterministic simulator until the owner approves a provider.

Authentication
API key (Bearer)
Permission
ai:read
Idempotency-Key
Not used
Success
200

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/ai/settings" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Turn AI features on or off

PUT/v1/ai/settings

Partial update of analystEnabled, editorEnabled and mcpEnabled; each change is audited (ai.settings_updated). Needs ai:manage.

Authentication
API key (Bearer)
Permission
ai:manage
Idempotency-Key
Required
Success
200

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • analystEnabledboolean
  • editorEnabledboolean
  • mcpEnabledboolean

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X PUT "$GIEP_API_URL/v1/ai/settings" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-settings-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "analystEnabled": false,
  "editorEnabled": false,
  "mcpEnabled": false
}'
// JSON object. The OpenAPI document does not list its fields.

AI usage meter: attempts and tokens per feature, with the daily quota

GET/v1/ai/usage

Per feature (analyst, editor): model attempts and tokens in and out from the usage records for the current UTC day and month, the daily quota, and how much of it the last 24 hours used. Needs ai:read.

Authentication
API key (Bearer)
Permission
ai:read
Idempotency-Key
Not used
Success
200

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/ai/usage" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Net revenue per checkout and per offer, per currency, with each term source

GET/v1/analytics/net-revenue

Gross minus discounts minus refunds minus processing fees (ledger) minus expected chargebacks (current ratio times volume). Offers allocate refunds and fees pro rata by share of the checkout gross.

Authentication
API key (Bearer)
Permission
payment:read
Idempotency-Key
Not used
Success
200

Query parameters

  • fromstring · date-timerequired

    ISO 8601 instant with Z or an offset, e.g. 2026-10-24T00:00:00Z

    pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • tostring · date-timerequired

    ISO 8601 instant with Z or an offset, e.g. 2026-10-24T00:00:00Z

    pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/analytics/net-revenue?from=1&to=1" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Draft a checkout with AI (saved as a draft, never published)

POST/v1/checkouts/{id}/draft-with-ai

The model proposes a config from GIEP components; products and prices come from the catalogue, invented prices, discounts, guarantees and countdowns are stripped, text is capped and generated sections are flagged aiGenerated. Only a draft that passes the pre-publish validator is saved (otherwise 422 with the issues). The merchant publishes as usual.

Authentication
API key (Bearer)
Permission
ai:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • promptstringrequired
    min 3 chars · max 2000 chars
  • assetsobject
    Fields: 4 fields
    • brandNamestring
      min 1 chars · max 80 chars
    • primaryColorstring
      pattern ^#[0-9a-fA-F]{6}$
    • logoUrlstring · uri
      max 2000 chars
    • productCopyarray<object>
      max 20 items
      Each item has 2 fields
      • productIdstring · uuidrequired
      • copystringrequired
        min 1 chars · max 1000 chars

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/checkouts/6d1e65ac-7d19-48d4-abb7-e70023aa/draft-with-ai" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-draft-with-ai-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "string"
}'
// JSON object. The OpenAPI document does not list its fields.

Whole-funnel experiments

GET/v1/experiments

Every experiment of the merchant with its status and variants.

Authentication
API key (Bearer)
Permission
ai:read
Idempotency-Key
Not used
Success
200

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/experiments" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Create an experiment (2-4 variants of one checkout, split in basis points)

POST/v1/experiments

Each variant is a published version of the checkout; shares add up to 10,000 bps; the first variant is the control. Audited.

Authentication
API key (Bearer)
Permission
ai:manage
Idempotency-Key
Required
Success
201

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • checkoutIdstring · uuidrequired
  • namestringrequired
    min 1 chars · max 120 chars
  • variantsarray<object>required
    min 2 items · max 4 items
    Each item has 3 fields
    • idstringrequired
      min 1 chars · max 40 chars
    • checkoutVersionIdstring · uuidrequired
    • bpsintegerrequired
      min 1 · max 10000

Responses

  • 201Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/experiments" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-experiments-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "checkoutId": "679010dc-dba5-41d2-a1d7-5b76-d95",
  "name": "string",
  "variants": [
    {
      "id": "string",
      "checkoutVersionId": "d0b8d2ce-790b-4b80-af6a-7d72-268",
      "bps": 1
    }
  ]
}'
// JSON object. The OpenAPI document does not list its fields.

One experiment

GET/v1/experiments/{id}

Status, variants, start and stop times and the stop reason.

Authentication
API key (Bearer)
Permission
ai:read
Idempotency-Key
Not used
Success
200

Path parameters

  • idstringrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/experiments/6d1e65ac-7d19-48d4-abb7-e70023aa" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

The variant for a checkout session

POST/v1/experiments/{id}/assign

Deterministic: the same session always gets the same variant (SHA-256 bucket of experiment and session over the split). Only while the experiment is running.

Authentication
API key (Bearer)
Permission
ai:read
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • sessionIdstring · uuidrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/experiments/6d1e65ac-7d19-48d4-abb7-e70023aa/assign" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-assign-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "sessionId": "be25a35a-5e48-4bac-a8c6-0c4a-30f"
}'
// JSON object. The OpenAPI document does not list its fields.

Experiment results per variant with significance and guardrail

GET/v1/experiments/{id}/results

Sessions, paid orders, conversion, revenue per session per currency, refunds, disputes and decline rate per variant; two-proportion z-test against the control. A winner is shown only with at least 100 conversions per arm and p below 0.05. Read-only: a variant whose decline rate exceeds the control by 10 points with at least 50 attempts is reported under guardrail.breached; a scheduled check (every 15 minutes) then stops the experiment (audited).

Authentication
API key (Bearer)
Permission
ai:read
Idempotency-Key
Not used
Success
200

Path parameters

  • idstringrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/experiments/6d1e65ac-7d19-48d4-abb7-e70023aa/results" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Start an experiment

POST/v1/experiments/{id}/start

One running experiment per checkout. Audited.

Authentication
API key (Bearer)
Permission
ai:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/experiments/6d1e65ac-7d19-48d4-abb7-e70023aa/start" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-start-v1"
// JSON object. The OpenAPI document does not list its fields.

Stop or conclude an experiment

POST/v1/experiments/{id}/stop

Set complete to mark it completed instead of stopped. Audited.

Authentication
API key (Bearer)
Permission
ai:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • reasonstring
    min 1 chars · max 200 chars
  • completeboolean

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/experiments/6d1e65ac-7d19-48d4-abb7-e70023aa/stop" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-stop-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string",
  "complete": false
}'
// JSON object. The OpenAPI document does not list its fields.
AI and insights · API reference · GIEP