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).

GET /dimensions/projects/:id

Get detailed information about a project: matching names, industry, business model, prompt counts per brand focus, 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 (array), business_model, target_audience, brand_voice, goals, primary_products (array), matching_names (array), prompts (array, max 100), 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).

PATCH /projects/:id

Update the project profile (the Brand Book plus brand matching), the same fields as Project Settings. 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 (rematching: true, edits blocked meanwhile); a brand_name change applies to future runs only. Unknown fields are rejected.

• Body (JSON), send only the fields to change: brand_name, description, industry (single key), business_model, target_audience, brand_voice, goals, primary_products (full replacement array), matching_names (FULL replacement array; send every variant to keep).

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_url must 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 with suggest=false opt-out; cold URLs can take up to ~2 minutes, set client timeout to 180s. Finalize is idempotent and re-validates every gate.