Projects
A project is one tracked brand: its domain, locale, prompts and competitors. Almost every other endpoint takes a project_id, so start here.
GET/dimensions/projects
Lists the authenticated user’s projects (this is also an auth check). Pitch projects, one-off snapshots deleted 90 days after they are created, are left out unless pitch=include or pitch=only.
GET/dimensions/projects/:id
Get detailed information about a project: matching names, additional owned domains, industry, business model, prompt counts per brand focus, the project's own prompt limit (prompt_limit, null without one) with stats.prompts_available (how many prompts can still be added: the lower of the project's room under that limit and the account's remaining prompts, null when neither applies), and data_coverage (the models, countries and languages that actually have data), so one call replaces separate models/locales lookups.
GET/dimensions/models
Lists models present in daily metrics for the project.
GET/dimensions/locales
Lists countries and languages present in daily metrics for the project.
POST/projects
Create a complete project in one call (fast mode): project, prompts (queued for execution + categorization), competitors, weekly email subscription. Idempotent when external_identifier is provided. The project always belongs to the account owner.
- Body (JSON):
website_url(required public HTTP(S) URL with a DNS hostname or public IP address; credentials, private and special IP addresses, localhost and internal hostnames are rejected),name(required),main_country(required),main_language(required),brand_name,description,industry(one key or an array; an unknown key is rejected with the valid keys listed),business_model,target_audience,brand_voice,goals,primary_products(array),matching_names(array),prompts(array, max 100),collections(array of {name, prompts}, max 50, each tagging prompts of the same request by their exact text),competitors(array of {domain, brand_name, matching_names}),owned_media(object, Growth+),use_subdomain,weekly_email_subscribed,external_identifier(embed-enabled accounts only; idempotency key, [a-z0-9_-]{1,64}),execute_prompts_immediately(default true),pitch(default false; true creates a pitch project, a one-off snapshot for a prospect that runs once, takes no project slot and is deleted after 90 days unless converted; it uses one of the month's pitch projects and takes 1 to 100 prompts).
PATCH/projects/:id
Update the project profile (the Brand Book plus brand matching), the same fields as Project Settings, the additional owned domains and the project's prompt limit. All seven Brand Book fields (industry, business_model, description, primary_products, target_audience, brand_voice, goals) feed every GEO Writer task and prompt suggestions. industry, description, and target_audience also help Recommendations calibrate their advice. Changing matching_names re-runs mention/citation matching over the project history in the background, and changing additional_owned_domains reprocesses the past answers that cite an added or removed domain (rematching: true, edits blocked meanwhile); a brand_name change applies to future runs only. Only the account owner can change additional_owned_domains. prompt_limit works as on Account Settings > Prompt Limits (a lower limit deletes no prompt), and a request that sends only it is saved even during a recalculation. pitch: false, sent on its own, converts a pitch project into a tracked project: it keeps its data, takes a project slot, its prompts run on the account's schedule, and it cannot be undone. Unknown fields are rejected, and a request is applied whole or not at all.
- Body (JSON), send only the fields to change:
name(a label; it does not change mention detection unlessbrand_nameis empty),brand_name,description,industry(one key, or an array stored as an array),business_model,target_audience,brand_voice,goals,primary_products(full replacement array),matching_names(FULL replacement array; send every variant to keep),additional_owned_domains(FULL replacement array of up to 10 domains, each a website's own domain, so a subdomain or a platform many companies share is refused;[]clears it; account owner only),prompt_limit(the most prompts the project can hold, as on Account Settings > Prompt Limits: a whole number from 1 to 2147483647, ornullto remove the limit; the account owner or an account admin (co-owner) with the Projects update permission; a key limited to some projects getsERR_KEY_PROJECT_SCOPED).
DELETE/projects/:id
Delete a project, like Delete Project in Project Settings. It cannot be undone: the project disappears at once and frees a project slot, then a background job deletes its prompts, answers, mentions, citations, sentiment, competitors and metrics history. API keys limited to the project lose it, and a key left with no project is revoked. A team member needs permission to delete projects.
:idproject id
A project the key cannot see, or one already being deleted, returns ERR_PROJECT_NOT_FOUND. Requires a read_write key not limited to some projects (otherwise ERR_KEY_PROJECT_SCOPED).
Project Drafts wizard
Multi-step project wizard with AI suggestions: POST /project_drafts starts a draft (returns suggested name/description/industry for the URL), PATCH submits each step (details, prompts, competitors, owned_media) with strict forward gating and returns suggestions for the next step, POST /project_drafts/:id/finalize creates the real project. Drafts expire after 24h.
- The initial
website_urlmust be a public HTTP(S) URL with a DNS hostname or public IP address. Credentials, private and special IP addresses, localhost and internal hostnames are rejected. Steps:details(name required),prompts(max 100, quota-validated),competitors(plan-capped),owned_media(optional, Growth+). Suggestions per step withsuggest=falseopt-out; cold URLs can take up to ~2 minutes, set client timeout to 180s. Finalize is idempotent and re-validates every gate.