With a key that has the Read and write permission, the API can create projects and change a project's name, markets, brand and competitors, its prompts and brand facts, and make and turn off report share links. Every other key stays read only. For the read addresses, see API reference.
Make a key that can write
Go to Settings, then API keys. Choose Read and write under Permissions and generate the key. Read only is the default. Only a workspace Admin can make keys.
A change made with the key counts as a change by the person who made the key, with the rights of a Member: it cannot reach Admin settings, and if an Admin limits that person to some projects, the key can change only those. If that person becomes a Viewer or leaves the workspace, the key can no longer make changes. Each change shows in the audit log with the source API and the key's name.
Addresses
| Method and address | What it does |
|---|---|
GET /projects/{id}/brands | The project's own brand (id brand) and its tracked competitors |
GET /projects/{id}/brands/{brandId} | One of them |
POST /projects | Creates a project. Send brand (name and domain) and markets (each with country, city and language) |
PATCH /projects/{id} | Renames the project or changes its markets. Send each market's id back to keep its prompts with it |
POST /projects/{id}/brands | Adds a competitor. Send name, and domain and aliases if you have them |
PATCH /projects/{id}/brands/{brandId} | Changes the brand (brand) or a competitor: name, domain, aliases, and for the brand category |
DELETE /projects/{id}/brands/{brandId} | Deletes a competitor. The brand itself cannot be deleted |
The same limits apply as in the app, such as the number of projects and competitors on your plan. Adding a competitor that is already tracked answers 409 conflict, and deleting the brand answers 409 own_brand. A read only key answers 403 insufficient_scope, and a key whose maker is no longer an Admin or Member answers 403 role_read_only.
Prompts
Every prompt has an id. The tracked prompts list at GET /projects/{id}/prompts shows results but no ids, so use the catalog to find them: it lists every prompt, active and paused.
| Method and address | What it does |
|---|---|
GET /projects/{id}/prompts/catalog | Every prompt with its id, text, topic, tags, market and status (active or paused), and the plan's promptLimit. Add status=paused or status=active to filter |
POST /projects/{id}/prompts | Adds up to 200 prompts. Send prompts, a list of objects with text, and optionally topic, tags and market (a market id from the catalog) |
PATCH /projects/{id}/prompts/{promptId} | Changes text, topic or tags. Its past answers stay with it, so reword the same question rather than asking a different one |
POST /projects/{id}/prompts/{promptId}/pause | Stops checking the prompt and keeps its history. A paused prompt does not count toward the limit |
POST /projects/{id}/prompts/{promptId}/resume | Checks a paused prompt again |
DELETE /projects/{id}/prompts/{promptId} | Deletes a paused prompt and its saved answers for good |
The same rules apply as in the app. A project can have a limited number of active prompts on its plan: adding prompts is all or nothing, and over the limit the answer is 403 prompt_limit. A prompt already tracked in the same market is skipped and counted in skipped; if every prompt in the request is already tracked, the answer is 409 duplicate_prompt. Only a paused prompt can be deleted (409 not_paused). A prompt text can be up to 500 characters, a topic 80, and a prompt can have up to 20 tags of 40 characters. A market the project does not have is a 400, and so is a name that cannot be tracked.
Shared reports
A shared report is a link that anyone can open to read the project's report, the same link as Share link on the Report page. The link's id is its token.
| Method and address | What it does |
|---|---|
GET /projects/{id}/shared-reports | The project's links, newest first, each with its url, expiresAt, status (live, expired or off) and whether it has a password. Only live links are listed unless you add include_closed=true |
POST /projects/{id}/shared-reports | Makes a link. Send days (a whole number from 1 to 180, 30 if you leave it out) and, if your workspace has share passwords, a password of at least 6 characters |
DELETE /projects/{id}/shared-reports/{linkId} | Turns a link off. Anyone who opens it afterwards is told it has expired |
A password is never shown again, and is not in the answer or the audit log.
Brand facts and fact checks
Brand facts are the statements the project checks AI answers against: a fact about the brand, or a mistaken claim AI should not repeat. The fact checks are the claims the checks flagged.
| Method and address | What it does |
|---|---|
GET /projects/{id}/facts | The facts, each with an id, a statement and a kind (true for a fact, false for a mistaken claim) |
POST /projects/{id}/facts | Adds facts. Send facts, a list of objects with statement and optionally kind (true by default) |
PATCH /projects/{id}/facts/{factId} | Changes statement or kind |
DELETE /projects/{id}/facts/{factId} | Deletes a fact. Claims already flagged against it stay in the fact checks |
GET /projects/{id}/fact-checks | The flagged claims, newest first, as the Accuracy page lists them: what the answer said (claim), what is wrong (issue), the engine, the prompt, the fact it was judged against and the pages it cited. Add status=open, reviewed or dismissed to filter |
A project holds up to 40 facts. Adding more than fit is a 400 too_many_facts and nothing is added. A statement can be up to 500 characters. The facts are saved as a whole list, as in the facts editor, so two people changing facts at the same moment can overwrite each other. Reviewing a flagged claim stays in the app.
Every change shows in the audit log with the source API and the key's name.
Try a change first
Add ?dry_run=true to any of these to see what would change. Nothing is changed, and any key can send one.