Genezio API Writes: Idempotency and Dry Runs

This page explains how to change the setup of a brand with the Genezio API. The routes that write use POST, PATCH and DELETE. They need a key with the write scope. A key that reads only gets 403 insufficient_scope. Each write does what the same change in the dashboard does: it checks the plan of the account, and it goes to the audit log of the account. Each entry gives the key and the address of the request:

{
  "via": "public_api",
  "api_key_id": 3,
  "api_key_name": "Nightly sync",
  "api_key_prefix": "gnz-ab12",
  "ip": "203.0.113.9"
}

To see what one key changed, search for its name on the Audit logs page of the dashboard.

Send a write again safely with an idempotency key

A network can fail after the API writes and before your program gets the answer. Send an Idempotency-Key header with each POST and PATCH, and send the same key again when you retry:

curl -X POST "https://app.backend.genezio.ai/customer/v1/brands/12/scenarios" \
  -H "X-API-Key: $GENEZIO_API_KEY" \
  -H "Idempotency-Key: 6f1c2a52-6a4b-4b52-9d6e-3d1c0f3b8f11" \
  -H "Content-Type: application/json" \
  -d '{"scenarios": [{"topic_id": 3, "text": "Which headphones are best for a flight?"}]}'

Case	Answer
First request with the key	The API writes and answers. It keeps the answer for 24 hours.
Same key, same request	The first answer again, with `Idempotent-Replayed: true`. Nothing is written a second time.
Same key, another body or route	`422 idempotency_key_reused`. Use a new key for each new write.
Same key while the first request runs	`409 idempotency_in_progress`. Send it again in a few seconds.
The first request got an error	The API does not keep an error. Thus, you can send the key again.

Use a new UUID for each write. A DELETE takes no key: a second delete gets 404.

Try a write first with a dry run

Each write of many items takes "dry_run": true. The API checks each item and gives the answer, but it writes nothing:

{
  "data": [],
  "rejected": [
    { "index": 1, "code": "not_found", "message": "Brand 12 has no topic 99." }
  ],
  "info": { "dry_run": true, "written": 2, "rejected": 1 }
}

Writes of many items and rejected items

A write of many items writes each item on its own. An item that is not valid is in rejected, with its index in your request and a code, and the other items are written:

{
  "data": [{ "id": 812, "topic_id": 3, "text": "Which headphones are best for a flight?", "status": "active", "created_at": "2026-10-06T09:12:44Z" }],
  "rejected": [{ "index": 1, "code": "conflict", "message": "Topic 3 already has this scenario." }],
  "info": { "dry_run": false, "written": 1, "rejected": 1 }
}

The plan of the account is checked for the items together. When the plan cannot hold them, the API writes nothing and answers 403 plan_limit_reached.

Create a topic with its scenarios

One request makes a topic and its scenarios:

{
  "topics": [
    {
      "name": "Headphones for travel",
      "type": "prompter",
      "language": "english",
      "answer_engines": ["chatgpt.com", "perplexity"],
      "scenarios": [
        "Which headphones are best for a long flight?",
        "Are noise-cancelling earbuds good for a train?"
      ]
    }
  ]
}

A topic with the name, the type and the language of another topic of the brand is rejected with conflict. A topic that the plan cannot hold is rejected with plan_limit_reached, and the topics before it stay written.

Change only what you send with PATCH

A PATCH changes only the fields of its body. The other fields keep their values. For the engines of a topic:

`answer_engines`	Result
not in the body	The engines do not change.
`["chatgpt.com"]`	The topic uses these engines. An engine that the plan does not hold gets `403 plan_limit_reached`.
`[]`	The topic uses the engines of the brand again.

What you can write with the API

Thing	Routes
Brand	Change the websites and the answer engines. `GET /brands/{brand_id}/models` gives each engine, in the plan or not.
Topics	Create many, each with its scenarios. Change one, pause or activate many, delete, restore.
Scenarios	Create many, change one, pause or activate many, delete, restore.
Competitors	Track many, change one, stop the tracking of one, delete. A name of a suggestion of the platform tracks the suggestion, with its history.
Brand groups	Create, change, give the whole list of members with one `PUT`, delete. A competitor is in one group at most: a second group gets `409`.
Tags	Create, change, delete, and give a topic its tags with one `PUT`. Each topic gives its tags in `tags`.
Personas	Create, change, delete. Give a persona to a topic with `persona_id`. A persona that a topic uses gets `409` on a delete.
Tracked URLs	Track many pages (a page with no title gets the title of the page), change one, stop the tracking of one. Put the pages in tracked URL groups: create, rename, delete. An address that the brand tracks gets `conflict`.
Knowledge bases	Create from a text, a site or files, crawl a site again, stop the indexing, delete. See below: these writes cost.
Scorecard	Change a goal, archive a goal, restore it.

A new scenario runs with the next run of its topic. A write does not start a run, thus it costs nothing. The API reads the articles, the briefs and the templates, but it does not write them. The dashboard writes them with a model. A tracked URL group is a folder for the tracked URLs of a brand, such as “Blog” or “Q4 campaign”. It is not a brand group. A brand group joins competitors into one brand.

Writes that have a cost

Most writes only change the setup, thus they cost nothing. These writes start work that costs, as the same action in the dashboard does:

Write	What it costs
Create a knowledge base	An embedding of each chunk. A site also costs a crawl of each page, up to `max_pages`.
Crawl a knowledge base again	A crawl of each page and an embedding of each chunk. A `schedule` does it by itself.
Search the knowledge bases	One embedding of the query.

The plan of the account limits the knowledge bases of a brand. A write over the limit gets 403 plan_limit_reached, and nothing is written.

Guides

API reference

Setup

Content

Analytics

Write data

Send a write again safely with an idempotency key

Try a write first with a dry run

Writes of many items and rejected items

Create a topic with its scenarios

Change only what you send with PATCH

What you can write with the API

Writes that have a cost

​Send a write again safely with an idempotency key

​Try a write first with a dry run

​Writes of many items and rejected items

​Create a topic with its scenarios

​Change only what you send with PATCH

​What you can write with the API

​Writes that have a cost

Send a write again safely with an idempotency key

Try a write first with a dry run

Writes of many items and rejected items

Create a topic with its scenarios

Change only what you send with PATCH

What you can write with the API

Writes that have a cost