Create and configure a project
#Start with GET /workspace to read plan limits, project usage, and prompt budget. Read GET /engines for active measurement engines. Create a project with POST /projects, or use an existing ID from the project list.
The limits object in the workspace response can also include crawler_access, api_access, and mcp_access. These fields are reserved and false on every plan, and a response may omit them. They do not show whether API, MCP, or crawler access is enabled for your workspace.
Project creation returns HTTP 201 and the new ID at data.brand.id. Its inputs include a public website root, country, language code, and IANA time zone. Project creation has no generic replay identity; reconcile an uncertain response before creating another project.
Use PATCH /projects/{projectId} to edit project settings, PUT /prompt-allocation to set its prompt budget, and PUT /engines to select entitled engines. All of these nested paths start with /projects/{projectId}.
Prepare the question set
#Add topics, competitors, and owned domains as needed. Brand profile fields supply context and writing guidance. Suggestion operations require write + generate and use the project's saved website and metadata.
To add tracked prompts, send POST /projects/{projectId}/prompts with a caller-generated requestId, optional topic ID, and prompt texts. Review generated proposals before using the accept endpoint. Archive or restore prompts individually or in bounded bulk batches.
Permanent prompt deletion removes its associated run history. PUT /prompts also replaces the curated set and deletes the old prompts and cascaded history. Use additive creation and archive when retaining measurement evidence. For curated topic confirmation, prefer atomic PUT /topics; compatibility POST /topics/accept replaces its tagged set without a single atomic transaction.
Tracking and analysis
#Use POST /projects/{projectId}/activate to activate tracking and POST /projects/{projectId}/analysis to prepare and enqueue today's analysis. These operations require write + generate and retain subscription, spend, enrichment, and queue guards. Send an empty JSON body.
Starting analysis returns HTTP 200 with data.ok and a numeric data.enqueued. It does not return a universal job ID. Poll GET /projects/{projectId}/analysis with read to inspect total, answered, failed, pending, promptsTotal, promptsDone, and outcome.
Readiness outcomes include running, ready, partial, and failed. A partial or failed result does not establish a measured zero. The API enqueues work through existing durable admission paths; background workers drain it.
Site audits and opportunity refresh use their own endpoints. Their HTTP 202 response includes a boolean enqueued and queued or not_enqueued state. A no-op response does not claim a new job was created.