Writes and idempotency

​

A key writes as the person who made it

• A key never does more than its maker could do in the app. An owner, admin or editor can make these changes; a viewer cannot.
• The maker is checked again on every write. If they have left the workspace or become a viewer, the key’s writes are refused with 403 forbidden (“the person who made this key can no longer change this workspace, so the key cannot either”). Its reads carry on. Make a new key as someone who can edit.
• A key with no recorded maker cannot write at all; make a new one.
• Turning on an engine that is an opt-in is a spending decision, so it needs an owner or admin, as in the app.
• Citino records every write against both the person and the key, so a change can always be traced to the key that made it.

​

Prompts

​

Add a prompt

• The same text again is 409 conflict with detail.existing_prompt_id (and detail.first_run_date). Identity is the exact text, so a retried script converges on that id. The match includes prompts you have archived or re-worded, which are not collected, so check that prompt’s status on the prompts list before treating it as live. Normalise your text (trim it, settle on one spelling) before you send it, because a different capital letter is a different prompt.
• A segment the project has not claimed is 409 conflict; detail.unclaimed and detail.claimed list both.
• At the plan’s prompt limit is 402 plan_limit, with detail.used, detail.limit and detail.actions naming the two ways out, upgrade and archive. The limit is checked before the duplicate, so at the limit even the same text again is 402, not 409.
• An archived project takes no new prompts: 409 conflict.

curl -X POST "https://api.citino.ai/v1/projects/$PROJECT_ID/prompts" -H "Authorization: Bearer $CITINO_API_KEY" -H "Content-Type: application/json" -d "{\"text\": \"$PROMPT_TEXT\", \"intent\": \"compare\", \"segments\": [\"$SEGMENT_ID\"]}"

import os
import requests

BASE = "https://api.citino.ai/v1"
key = os.environ["CITINO_API_KEY"]
project_id = os.environ["PROJECT_ID"]


def add_prompt(text, intent, segments):
    """Add a prompt, or return the id of the identical one already there."""
    response = requests.post(
        f"{BASE}/projects/{project_id}/prompts",
        headers={"Authorization": f"Bearer {key}"},
        json={"text": text.strip(), "intent": intent, "segments": segments},
    )
    if response.status_code == 409:
        detail = response.json()["error"].get("detail", {})
        if "existing_prompt_id" in detail:
            return detail["existing_prompt_id"]
    response.raise_for_status()
    return response.json()["prompt_id"]


print(add_prompt(os.environ["PROMPT_TEXT"], "compare", [os.environ["SEGMENT_ID"]]))

const BASE = "https://api.citino.ai/v1";
const headers = {
  Authorization: `Bearer ${process.env.CITINO_API_KEY}`,
  "Content-Type": "application/json",
};

// Add a prompt, or return the id of the identical one already there.
async function addPrompt(text, intent, segments) {
  const response = await fetch(`${BASE}/projects/${process.env.PROJECT_ID}/prompts`, {
    method: "POST",
    headers,
    body: JSON.stringify({ text: text.trim(), intent, segments }),
  });
  const body = await response.json();
  if (response.status === 409 && body.error.detail?.existing_prompt_id) {
    return body.error.detail.existing_prompt_id;
  }
  if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body.prompt_id;
}

console.log(await addPrompt(process.env.PROMPT_TEXT, "compare", [process.env.SEGMENT_ID]));

​

Re-word a prompt

​

Archive a prompt

​

Competitors

​

Track a competitor

• 201 with the brand’s brand_id, name and domain when it was added, and 200 with the same body when it was already tracked, so a retry is safe.
• An unknown brand id is 404; your own brand is 400, with field set to brand_id; at the plan’s competitor limit, 402 plan_limit with detail.limit and detail.used.

​

Stop tracking a competitor

​

Aliases

• POST …/aliases with {"alias": "…"} answers 201 with alias_id, brand_id and rescan, a sentence saying the answers already collected are being re-scanned for the new name (or, when the re-scan could not be queued just then, that the alias is saved and how to start the re-scan). The re-scan reads stored answers only: no engine is asked anything and no prompt allowance is used.
• An alias that already belongs to another brand is 409 conflict, and detail.owning_brand_id and detail.owning_brand_name name that brand. An alias is 3 to 128 characters; outside that is 400 validation.
• DELETE …/aliases/{aliasId} answers 204. Only an alias your workspace added that has not been reviewed yet can be removed (source is customer and reviewed is false); any other id is 404. Your project’s aliases and their ids are on GET /v1/projects/{projectId}; read them before adding, so a re-run does not add twice.

​

Segments and engines

• PUT …/segments with {"segments": [ids]} sets the segments the project claims: at least one, taken from the project’s segments on GET /v1/projects/{projectId}. An id the project does not have is 400 validation with field set to segments and the id in the message, and nothing changes; an id sent twice is claimed once. Your scores are recomputed over the history already stored on the next read; nothing new is collected. The answer has claimed and recomputed, a sentence saying so.
• PUT …/engines with {"engines": [keys]} sets the engines the project samples from now on. Turning one off removes nothing already measured. At least one must be an engine that is being collected (400 otherwise); an opt-in engine your plan does not carry is 402. The answer has engines, as stored, and history, a sentence saying what happened to past answers. GET /v1/engines lists every engine and how a project gets it.

​

Retrying safely

​

Related