{ "openapi": "3.1.0", "info": { "title": "Geogen API", "description": "API for accessing LLM visibility data, managing entities, and tracking AI mentions.", "version": "1.0.0" }, "servers": [ { "url": "https://api.geogen.io/v1", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key authentication. Format: Bearer wsk_your_api_key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "description": "Workspace ID" }, "name": { "type": "string", "description": "Workspace name" } } }, "Subscription": { "type": "object", "properties": { "planName": { "type": "string", "description": "Name of the subscription plan" }, "status": { "type": "string", "description": "Subscription status" }, "expiresAt": { "type": "number", "description": "Expiration timestamp in milliseconds" } } }, "UsageItem": { "type": "object", "properties": { "used": { "type": "number", "description": "Current usage count" }, "limit": { "type": "number", "nullable": true, "description": "Maximum allowed by plan" } } }, "Credits": { "type": "object", "properties": { "balance": { "type": "number", "description": "Current credit balance" }, "totalUsed": { "type": "number", "description": "Total credits used" } } }, "Entity": { "type": "object", "properties": { "id": { "type": "string", "description": "Entity ID" }, "name": { "type": "string", "description": "Entity name" }, "target": { "type": "string", "description": "Target URL or domain" }, "targetType": { "type": "string", "enum": [ "url", "term" ], "description": "Type of target" }, "description": { "type": "string", "description": "Entity description" }, "faviconUrl": { "type": "string", "description": "Favicon URL" }, "language": { "type": "string", "description": "Language code" }, "geolocation": { "type": "string", "description": "Geolocation code" }, "isActive": { "type": "boolean", "description": "Whether entity is active" } } }, "Prompt": { "type": "object", "properties": { "id": { "type": "string", "description": "Prompt ID" }, "prompt": { "type": "string", "description": "Prompt text" }, "language": { "type": "string", "description": "Language code" }, "geolocation": { "type": "string", "description": "Geolocation code" }, "createdAt": { "type": "number", "description": "Creation timestamp" } } }, "Model": { "type": "object", "properties": { "id": { "type": "string", "description": "Model ID" }, "uuid": { "type": "string", "description": "Model UUID (use for filtering)" }, "name": { "type": "string", "description": "Model name" }, "description": { "type": "string", "description": "Model description" } } }, "TeamMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Member ID" }, "userId": { "type": "string", "description": "User ID" }, "email": { "type": "string", "description": "Email address" }, "name": { "type": "string", "description": "Full name" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Role in workspace" }, "status": { "type": "string", "description": "Member status" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag ID" }, "name": { "type": "string", "description": "Tag name" }, "color": { "type": "string", "description": "Tag color" } } }, "Pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total count" }, "limit": { "type": "number", "description": "Items per page" }, "offset": { "type": "number", "description": "Current offset" } } }, "DomainGroupEntity": { "type": "object", "description": "A single entity inside a domain group, enriched with display data.", "properties": { "entityId": { "type": "string", "nullable": true, "description": "Tracking ID for the entity in this workspace (null when the entity is not tracked here, e.g. a competitor)." }, "entityUuid": { "type": "string", "description": "Stable, system-wide entity UUID." }, "name": { "type": "string", "nullable": true, "description": "Entity display name." }, "target": { "type": "string", "nullable": true, "description": "Entity domain or term." }, "faviconUrl": { "type": "string", "nullable": true, "description": "Favicon URL for the entity, if known." }, "isPrimary": { "type": "boolean", "description": "Whether this entity is the group's primary entity (its name/favicon represent the group)." }, "inWorkspace": { "type": "boolean", "description": "Whether this entity is tracked in the current workspace." } } }, "DomainGroup": { "type": "object", "description": "A group of entities that represent the same brand. Analytics for grouped entities are merged across all pages and responses.", "properties": { "id": { "type": "string", "description": "Domain group ID." }, "name": { "type": "string", "description": "Display name for the group." }, "primaryEntityUuid": { "type": "string", "description": "UUID of the entity whose name and favicon represent the group." }, "entityTrackingId": { "type": "string", "nullable": true, "description": "Optional entity-tracking scope. When set, the group only applies to analytics generated under this specific tracking." }, "entities": { "type": "array", "description": "Entities included in the group. The entity with `isPrimary=true` represents the group.", "items": { "$ref": "#/components/schemas/DomainGroupEntity" } }, "createdAt": { "type": "number", "description": "Creation timestamp (ms)." }, "updatedAt": { "type": "number", "description": "Last update timestamp (ms)." } } } } }, "paths": { "/workspace": { "get": { "operationId": "getWorkspace", "summary": "Get Workspace", "description": "Get workspace information, usage limits, and credit balance.", "tags": [ "Workspace" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "subscription": { "$ref": "#/components/schemas/Subscription" }, "usage": { "type": "object", "properties": { "entities": { "$ref": "#/components/schemas/UsageItem" }, "prompts": { "$ref": "#/components/schemas/UsageItem" }, "teamMembers": { "$ref": "#/components/schemas/UsageItem" }, "credits": { "$ref": "#/components/schemas/Credits" } } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workspace/members": { "get": { "operationId": "getWorkspaceMembers", "summary": "Get Workspace Members", "description": "Get all team members in the workspace.", "tags": [ "Workspace" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } }, "count": { "type": "number" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workspace/tags": { "get": { "operationId": "getWorkspaceTags", "summary": "Get Workspace Tags", "description": "Get all tags in the workspace.", "tags": [ "Workspace" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "count": { "type": "number" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/entities": { "get": { "operationId": "getEntities", "summary": "Get Entities", "description": "Get all entities in the workspace.", "tags": [ "Entities" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } }, "count": { "type": "number" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createEntity", "summary": "Create Entity", "description": "Create a new entity and start tracking its visibility across LLMs.\n\nPrompts can be handled in three ways:\n- **Custom prompts**: Provide your own prompts via the `prompts` array. Each prompt can be a simple string (inherits the entity's `language` and `geolocation`) or an object with per-prompt `language` and `geolocation` overrides.\n- **Auto-generate** (default): Omit the `prompts` field and AI will generate relevant prompts based on the entity's description, language, and geolocation.\n- **No prompts**: Set `generatePrompts` to `false` to create the entity without any prompts. You can add prompts later via the Add Prompt endpoint.", "tags": [ "Entities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "domain", "models" ], "properties": { "name": { "type": "string", "description": "Entity display name" }, "domain": { "type": "string", "description": "Website domain (e.g., example.com)" }, "models": { "type": "array", "items": { "type": "string" }, "description": "Array of model UUIDs from /v1/models" }, "description": { "type": "string", "description": "Entity description" }, "language": { "type": "string", "default": "en", "description": "Language code for the entity (e.g., 'en', 'fr', 'de'). Used as default for auto-generated prompts and for custom prompts that don't specify their own language." }, "geolocation": { "type": "string", "default": "global", "description": "Geolocation code for the entity (e.g., 'global', 'us', 'gb'). Used as default for auto-generated prompts and for custom prompts that don't specify their own geolocation." }, "trackingType": { "type": "string", "enum": [ "website", "individual" ], "default": "website", "description": "Type of tracking" }, "prompts": { "type": "array", "items": { "oneOf": [ { "type": "string", "description": "Prompt text (uses entity's language and geolocation)" }, { "type": "object", "required": ["prompt"], "properties": { "prompt": { "type": "string", "description": "Prompt text" }, "language": { "type": "string", "description": "Language override for this prompt (e.g., 'fr', 'de'). Defaults to entity's language." }, "geolocation": { "type": "string", "description": "Geolocation override for this prompt (e.g., 'us', 'gb'). Defaults to entity's geolocation." } } } ] }, "description": "Custom prompts for tracking. Each item can be a plain string (inherits entity's language/geolocation) or an object with per-prompt language/geolocation overrides. When provided, auto-generation is skipped." }, "generatePrompts": { "type": "boolean", "default": true, "description": "Whether to auto-generate prompts using AI. Ignored when the `prompts` array is provided. Set to `false` to create the entity without any prompts." }, "startTracking": { "type": "boolean", "default": true, "description": "Start tracking immediately" } } }, "examples": { "with_custom_prompts_simple": { "summary": "Custom prompts (strings)", "description": "Simple string prompts that inherit the entity's language and geolocation.", "value": { "name": "Mon Site", "domain": "example.fr", "description": "Plateforme de gestion de projet pour les équipes distantes", "language": "fr", "geolocation": "fr", "trackingType": "website", "models": [ "model-uuid-1", "model-uuid-2" ], "prompts": [ "Quel est le meilleur outil de gestion de projet pour les équipes à distance ?", "Quels logiciels recommandez-vous pour la collaboration en ligne ?", "Quelles sont les meilleures alternatives à Trello en France ?" ], "startTracking": true } }, "with_custom_prompts_mixed": { "summary": "Custom prompts (per-prompt language/geo)", "description": "Mix of strings and objects. Strings inherit entity defaults, objects can override language and geolocation per prompt.", "value": { "name": "My Website", "domain": "example.com", "description": "Project management platform for remote teams", "language": "en", "geolocation": "us", "trackingType": "website", "models": [ "model-uuid-1", "model-uuid-2" ], "prompts": [ "What is the best project management tool for remote teams?", { "prompt": "Quel est le meilleur outil de gestion de projet ?", "language": "fr", "geolocation": "fr" }, { "prompt": "What are the top project management tools in the UK?", "geolocation": "gb" } ], "startTracking": true } }, "auto_generate_prompts": { "summary": "Auto-generated prompts (default)", "description": "Omit the prompts field to let AI generate relevant prompts based on the entity's description, language, and geolocation.", "value": { "name": "My Website", "domain": "example.com", "description": "Project management platform for remote teams with task tracking and time management features", "language": "en", "geolocation": "us", "trackingType": "website", "models": [ "model-uuid-1", "model-uuid-2" ], "startTracking": true } }, "no_prompts": { "summary": "Without prompts", "description": "Create the entity without any prompts. You can add prompts later via the Add Prompt endpoint.", "value": { "name": "My Website", "domain": "example.com", "description": "Project management platform for remote teams", "language": "en", "geolocation": "global", "trackingType": "website", "models": [ "model-uuid-1", "model-uuid-2" ], "generatePrompts": false, "startTracking": true } } } } } }, "responses": { "201": { "description": "Entity created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Entity" }, "promptsGenerated": { "type": "number", "description": "Number of prompts saved for this entity (0 if generatePrompts was false and no custom prompts were provided)" }, "prompts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Prompt ID" }, "prompt": { "type": "string", "description": "The prompt text" }, "language": { "type": "string", "description": "Language code (per-prompt override or inherited from the entity)" }, "geolocation": { "type": "string", "description": "Geolocation code (per-prompt override or inherited from the entity)" } } }, "description": "The saved prompts for this entity. Each prompt has its own language and geolocation (either per-prompt override or inherited from the entity)." }, "trackingStarted": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfter": { "type": "number" } } } } } } } }, "patch": { "operationId": "updateEntity", "summary": "Update Entity", "description": "Update an existing entity's properties such as domain, description, language, geolocation, or tracked models. Only the fields provided in the request body will be updated.\n\n**Note:** Entity names cannot be changed directly. Use the `POST /entities/name-request` endpoint to submit a name correction request for admin review.", "tags": [ "Entities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entityId" ], "properties": { "entityId": { "type": "string", "description": "The ID of the entity to update" }, "target": { "type": "string", "description": "New website domain (e.g., example.com)" }, "description": { "type": "string", "description": "New entity description" }, "language": { "type": "string", "description": "New language code (e.g., 'en', 'fr', 'de')" }, "geolocation": { "type": "string", "description": "New geolocation code (e.g., 'global', 'us', 'gb')" }, "models": { "type": "array", "items": { "type": "string" }, "description": "New array of model UUIDs from /v1/models. Must contain at least 1 model." } } }, "examples": { "update_description": { "summary": "Update description", "value": { "entityId": "abc123def456", "description": "Updated description for the entity" } }, "update_domain": { "summary": "Update domain", "value": { "entityId": "abc123def456", "target": "newdomain.com" } }, "update_models": { "summary": "Update tracked models", "value": { "entityId": "abc123def456", "models": [ "model-uuid-1", "model-uuid-2", "model-uuid-3" ] } } } } } }, "responses": { "200": { "description": "Entity updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Entity ID" }, "name": { "type": "string", "description": "Entity name" }, "target": { "type": "string", "description": "Entity domain/URL" }, "targetType": { "type": "string", "enum": ["url", "term"], "description": "Type of target" }, "description": { "type": "string", "description": "Entity description" }, "language": { "type": "string", "description": "Language code" }, "geolocation": { "type": "string", "description": "Geolocation code" }, "models": { "type": "array", "items": { "type": "string" }, "description": "Selected model UUIDs" }, "isActive": { "type": "boolean", "description": "Whether the entity is active" }, "createdAt": { "type": "number", "description": "Creation timestamp" }, "updatedAt": { "type": "number", "description": "Last update timestamp" } } }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Domain conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfter": { "type": "number" } } } } } } } }, "delete": { "operationId": "removeEntity", "summary": "Remove Entity", "description": "Remove an entity from your workspace. This detaches the entity from your workspace and cleans up all associated data including sharing records, metadata, schedules, and competitor selections.\n\n**Important:** The entity itself and its historical data (prompts, responses, mentions, citations) are preserved and not deleted. The entity becomes orphaned and can be reclaimed if another user adds the same target.", "tags": [ "Entities" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The ID of the entity to remove" } ], "responses": { "200": { "description": "Entity removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "description": "Confirmation message" }, "deleted": { "type": "object", "description": "Counts of deleted records", "properties": { "sharedEntities": { "type": "number", "description": "Number of sharing records removed" }, "metadata": { "type": "number", "description": "Number of metadata records removed" }, "schedule": { "type": "number", "description": "Number of schedule records removed" }, "competitorSelections": { "type": "number", "description": "Number of competitor selection records removed" } } } } }, "example": { "success": true, "message": "Entity has been removed from your workspace. The entity data is preserved.", "deleted": { "sharedEntities": 0, "metadata": 1, "schedule": 1, "competitorSelections": 2 } } } } }, "400": { "description": "Bad request - missing or invalid entityId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfter": { "type": "number" } } } } } } } } }, "/entities/check-domain": { "get": { "operationId": "checkDomainAvailability", "summary": "Check Domain Availability", "description": "Check if a domain is available for tracking before creating an entity. Returns whether the domain is available, already in your workspace, or tracked by another user.", "tags": [ "Entities" ], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Domain to check (e.g., example.com or https://example.com)" } ], "responses": { "200": { "description": "Domain availability check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "available": { "type": "boolean", "description": "Whether the domain is available for tracking" }, "reason": { "type": "string", "enum": [ "not_tracked", "already_in_workspace", "tracked_by_another_user" ], "description": "Reason for the availability status" }, "message": { "type": "string", "description": "Human-readable explanation" } } }, "examples": { "available": { "summary": "Domain is available", "value": { "success": true, "available": true, "reason": "not_tracked", "message": "This domain is available for tracking." } }, "already_tracked": { "summary": "Domain already in workspace", "value": { "success": true, "available": false, "reason": "already_in_workspace", "message": "This domain is already tracked in your workspace." } }, "taken": { "summary": "Domain tracked by another user", "value": { "success": true, "available": false, "reason": "tracked_by_another_user", "message": "This domain is already being tracked by another user." } } } } } }, "400": { "description": "Missing domain parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfter": { "type": "number" } } } } } } } } }, "/entities/prompts": { "get": { "operationId": "getEntityPrompts", "summary": "Get Entity Prompts", "description": "Get prompts for a specific entity with performance stats.", "tags": [ "Entities" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "14d", "30d" ] }, "description": "Time period" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Start date (ISO format)" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "End date (ISO format)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Prompt" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/entities/addprompt": { "post": { "operationId": "addPrompt", "summary": "Add Prompt(s)", "description": "Create one or more prompts for an entity. Supports both single prompt and bulk upload modes.\n\n**Single prompt mode:** Use `prompt` field with a string value.\n\n**Bulk upload mode:** Use `prompts` field with an array of prompt objects. Each object can have its own language/geolocation, or inherit from the top-level defaults.", "tags": [ "Entities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entityId" ], "properties": { "entityId": { "type": "string", "description": "Entity ID" }, "prompt": { "type": "string", "description": "Prompt text (for single prompt mode)" }, "prompts": { "type": "array", "description": "Array of prompts (for bulk upload mode)", "items": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Prompt text" }, "language": { "type": "string", "description": "Language code (overrides default)" }, "geolocation": { "type": "string", "description": "Geolocation code (overrides default)" } } } }, "language": { "type": "string", "description": "Default language code for prompts" }, "geolocation": { "type": "string", "description": "Default geolocation code for prompts" } } }, "examples": { "single": { "summary": "Single prompt", "value": { "entityId": "abc123def456...", "prompt": "What are the best tools for SEO?", "language": "en", "geolocation": "us" } }, "bulk": { "summary": "Bulk upload", "value": { "entityId": "abc123def456...", "prompts": [ { "prompt": "What are the best SEO tools?" }, { "prompt": "Quelles sont les meilleures outils SEO?", "language": "fr" }, { "prompt": "What is the best marketing software in UK?", "geolocation": "gb" } ], "language": "en", "geolocation": "global" } } } } } }, "responses": { "201": { "description": "Prompt(s) created successfully", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Single prompt response", "properties": { "success": { "type": "boolean" }, "promptId": { "type": "string", "description": "Created prompt ID" } } }, { "type": "object", "description": "Bulk upload response", "properties": { "success": { "type": "boolean" }, "promptIds": { "type": "array", "items": { "type": "string" }, "description": "Array of created prompt IDs" }, "count": { "type": "number", "description": "Number of prompts created" } } } ] } } } }, "400": { "description": "Bad request - invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Prompt limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/entities/updateprompt": { "patch": { "operationId": "updatePrompt", "summary": "Update Prompt(s)", "description": "Update one or more prompts in a single request.\n\n**Single mode** — supply `promptId` plus any subset of editable fields (`prompt`, `language`, `geolocation`, `isActive`). Returns the updated prompt.\n\n**Batch mode** — supply `updates: [...]` where each entry carries its own `promptId` and the fields to change for that prompt. Different prompts can receive different patches in the same call. Maximum 100 updates per request.\n\nSet `isActive` to `false` to pause tracking for a prompt without deleting it.", "tags": [ "Entities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Single update", "type": "object", "required": [ "promptId" ], "properties": { "promptId": { "type": "string", "description": "Prompt ID to update" }, "prompt": { "type": "string", "description": "New prompt text" }, "language": { "type": "string", "description": "New language code (e.g., 'en', 'fr', 'de')" }, "geolocation": { "type": "string", "description": "New geolocation code (e.g., 'global', 'us', 'gb')" }, "isActive": { "type": "boolean", "description": "Set to false to pause tracking for this prompt, or true to re-activate it" } } }, { "title": "Batch update", "type": "object", "required": [ "updates" ], "properties": { "updates": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Array of per-prompt patches. Each entry must include `promptId` and at least one editable field.", "items": { "type": "object", "required": [ "promptId" ], "properties": { "promptId": { "type": "string", "description": "Prompt ID to update" }, "prompt": { "type": "string", "description": "New prompt text" }, "language": { "type": "string", "description": "New language code (e.g., 'en', 'fr', 'de')" }, "geolocation": { "type": "string", "description": "New geolocation code (e.g., 'global', 'us', 'gb')" }, "isActive": { "type": "boolean", "description": "Set to false to pause tracking for this prompt, or true to re-activate it" } } } } } } ] }, "examples": { "update_text": { "summary": "Update prompt text (single)", "value": { "promptId": "abc123def456...", "prompt": "What are the best tools for SEO in 2026?" } }, "update_language_geo": { "summary": "Update language and geolocation (single)", "value": { "promptId": "abc123def456...", "language": "fr", "geolocation": "fr" } }, "deactivate_prompt": { "summary": "Deactivate a prompt (single)", "value": { "promptId": "abc123def456...", "isActive": false } }, "batch_mixed": { "summary": "Batch update with different fields per prompt", "value": { "updates": [ { "promptId": "abc123def456...", "prompt": "Rewritten prompt copy" }, { "promptId": "ghi789jkl012...", "language": "fr", "isActive": true }, { "promptId": "mno345pqr678...", "isActive": false } ] } } } } } }, "responses": { "200": { "description": "Prompt(s) updated successfully. Single mode returns the updated prompt; batch mode returns per-item results.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Single update response", "type": "object", "properties": { "success": { "type": "boolean" }, "prompt": { "$ref": "#/components/schemas/Prompt" } } }, { "title": "Batch update response", "type": "object", "properties": { "success": { "type": "boolean" }, "updatedCount": { "type": "integer", "description": "Number of prompts successfully updated" }, "requestedCount": { "type": "integer", "description": "Number of prompts requested in the batch" }, "results": { "type": "array", "items": { "type": "object", "properties": { "promptId": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "string", "description": "Present only when `success` is false" }, "prompt": { "description": "Updated prompt object; present only when `success` is true", "$ref": "#/components/schemas/Prompt" } } } } } } ] } } } }, "400": { "description": "Bad request - invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Prompt not found (single mode only). In batch mode, per-prompt not-found errors are returned inside `results[]` with a 200 response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/entities/deleteprompt": { "delete": { "operationId": "deletePrompt", "summary": "Delete Prompt(s)", "description": "Delete one or more prompts. Supply either `promptId` (single) or `promptIds` (batch) via query parameters, or a JSON body with `{ \"promptId\": \"...\" }` or `{ \"promptIds\": [\"...\", \"...\"] }`. Maximum 100 IDs per batch request.", "tags": [ "Entities" ], "parameters": [ { "name": "promptId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Single prompt ID to delete (mutually exclusive with promptIds)." }, { "name": "promptIds", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of prompt IDs to delete (max 100)." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "promptId": { "type": "string" } } }, { "type": "object", "properties": { "promptIds": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } } } ] } } } }, "responses": { "200": { "description": "Prompt(s) deleted successfully", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean" } } }, { "type": "object", "properties": { "success": { "type": "boolean" }, "deletedCount": { "type": "integer" }, "requestedCount": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "promptId": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "string" } } } } } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Prompt not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/entities/name-request": { "post": { "operationId": "submitNameRequest", "summary": "Submit Name Change Request", "description": "Submit a request to correct an entity's display name. Entity names are global shared data and cannot be changed directly. Instead, submit a name correction request that will be reviewed by an admin.\n\n**Limit:** One pending request per entity per workspace.", "tags": [ "Entities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entityId", "suggestedName" ], "properties": { "entityId": { "type": "string", "description": "The ID of the entity to request a name change for" }, "suggestedName": { "type": "string", "description": "The suggested correct name" }, "reason": { "type": "string", "description": "Optional reason for the name change" } } }, "examples": { "basic": { "summary": "Request name correction", "value": { "entityId": "abc123def456", "suggestedName": "Correct Company Name", "reason": "The current name has a typo" } } } } } }, "responses": { "201": { "description": "Request submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request or duplicate pending request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getNameRequestStatus", "summary": "Get Name Request Status", "description": "Check the status of a name change request for an entity. Returns the most recent request with its current status (pending, approved, or rejected).", "tags": [ "Entities" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The ID of the entity to check" } ], "responses": { "200": { "description": "Request status returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "nullable": true, "description": "The name change request, or null if none exists", "properties": { "id": { "type": "string", "description": "Request ID" }, "currentName": { "type": "string", "description": "The entity's name when the request was made" }, "suggestedName": { "type": "string", "description": "The suggested new name" }, "reason": { "type": "string", "nullable": true, "description": "Reason provided for the change" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "description": "Current status of the request" }, "createdAt": { "type": "number", "description": "Timestamp when the request was submitted" }, "reviewedAt": { "type": "number", "nullable": true, "description": "Timestamp when the request was reviewed" }, "reviewNote": { "type": "string", "nullable": true, "description": "Note from the admin reviewer" } } }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/entities/tracking-status": { "get": { "operationId": "getEntityTrackingStatus", "summary": "Get Tracking Status", "description": "Get the mention check status for an entity. Returns when the last check completed, when the next check is scheduled, and whether a check is currently in progress. Useful for syncing — poll this endpoint to know when new data is available.", "tags": [ "Entities" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" } ], "responses": { "200": { "description": "Tracking status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "scheduled": { "type": "boolean", "description": "Whether the entity has a tracking schedule" }, "lastCheckCompletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO timestamp of the last completed mention check, or null if no check has completed yet" }, "nextCheckScheduledAt": { "type": "string", "format": "date-time", "description": "ISO timestamp of the next scheduled mention check" }, "isProcessing": { "type": "boolean", "description": "Whether a mention check is currently in progress" }, "frequencyHours": { "type": "number", "description": "How often mention checks run (in hours)" } } } } }, "examples": { "scheduled": { "summary": "Entity with active tracking", "value": { "success": true, "data": { "scheduled": true, "lastCheckCompletedAt": "2026-03-06T10:00:00.000Z", "nextCheckScheduledAt": "2026-03-07T10:00:00.000Z", "isProcessing": false, "frequencyHours": 24 } } }, "not_scheduled": { "summary": "Entity without tracking schedule", "value": { "success": true, "data": { "scheduled": false, "message": "No tracking schedule found for this entity" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/entities/citations": { "get": { "operationId": "getEntityCitations", "summary": "Get Citations", "description": "Get top cited domains.", "tags": [ "Entities" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "14d", "30d" ] }, "description": "Time period" }, { "name": "models", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated model UUIDs" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Pagination offset" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated tag IDs to filter prompts by" }, { "name": "promptIds", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated prompt IDs to filter by specific prompts" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "number" }, "domain": { "type": "string" }, "name": { "type": "string" }, "totalCitations": { "type": "number" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/entities/citations/details": { "get": { "operationId": "getCitationDetails", "summary": "Get Citation Details", "description": "Get detailed URLs for a specific cited domain. Use the citedEntityUuid from the Get Citations endpoint to retrieve the individual citation URLs.", "tags": [ "Entities" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" }, { "name": "citedEntityUuid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "UUID of the cited entity (from Get Citations response)" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "14d", "30d" ] }, "description": "Time period" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Start date (ISO format)" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "End date (ISO format)" }, { "name": "models", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated model UUIDs" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The cited URL" }, "citationCount": { "type": "number", "description": "Number of times this URL was cited" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "period": { "type": "string", "description": "The time period used for the query" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/competitors": { "get": { "operationId": "getCompetitors", "summary": "Get Competitors", "description": "Get competitors visibility leaderboard.\n\n**Domain groups:** if the queried entity or any of its competitors belongs to a domain group in this workspace, entities sharing the same group are collapsed into a single row in the leaderboard, with mentions summed and avg position/sentiment computed as a mention-weighted average. The merged row reports the group's primary entity identity and includes `groupName` and `groupEntityUuids` so clients can render a badge.", "tags": [ "Analytics" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "14d", "30d" ] }, "description": "Time period" }, { "name": "models", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated model UUIDs" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "number" }, "entityUuid": { "type": "string", "description": "Entity UUID. For merged group rows, the primary entity's UUID." }, "domain": { "type": "string" }, "name": { "type": "string" }, "visibility": { "type": "number", "description": "Percentage of responses mentioning this entity (or any member of its domain group)." }, "mentions": { "type": "number", "description": "Total number of mentions (summed across the domain group when applicable)." }, "avgPosition": { "type": "number", "nullable": true, "description": "Mention-weighted average position across the domain group." }, "avgSentiment": { "type": "number", "nullable": true, "description": "Mention-weighted average sentiment across the domain group." }, "isCurrentEntity": { "type": "boolean", "description": "True if this row represents the queried entity or any of its domain-group siblings." }, "groupName": { "type": "string", "description": "Present only when the row was assembled from a domain group; the group's display name." }, "groupEntityUuids": { "type": "array", "items": { "type": "string" }, "description": "Present only when the row was assembled from a domain group; all entity UUIDs that merged into this row." } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/responses": { "get": { "operationId": "getResponses", "summary": "Get LLM Responses", "description": "Get LLM responses with mention status.", "tags": [ "Analytics" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "14d", "30d" ] }, "description": "Time period" }, { "name": "models", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated model UUIDs" }, { "name": "mentionStatus", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "mentioned", "not-mentioned" ] }, "description": "Filter by mention status" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Pagination offset" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated tag IDs to filter prompts by" }, { "name": "promptIds", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated prompt IDs to filter by specific prompts" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/responses/details": { "get": { "operationId": "getResponseDetails", "summary": "Get Response Details", "description": "Get comprehensive details for a single LLM response, including all mentions, citations, and query fanouts associated with it.", "tags": [ "Analytics" ], "parameters": [ { "name": "responseId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Response UUID (from the /responses endpoint)" }, { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID to get mention context for" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "response": { "type": "object", "properties": { "responseId": { "type": "string", "description": "Response UUID" }, "responseText": { "type": "string", "description": "Full response text from the LLM" }, "responseLength": { "type": "number", "description": "Length of response in characters" }, "createdAt": { "type": "string", "description": "ISO timestamp when response was created" }, "modelId": { "type": "string", "description": "Model UUID that generated this response" }, "isMentioned": { "type": "boolean", "description": "Whether the entity was mentioned in this response" }, "mentionPosition": { "type": "number", "nullable": true, "description": "Position of entity mention in the ranked list (if applicable)" }, "mentionSentiment": { "type": "number", "nullable": true, "description": "Sentiment score of entity mention (-1 to 1)" }, "totalOptionsInList": { "type": "number", "nullable": true, "description": "Total items in the ranked list (if applicable)" } } }, "prompt": { "type": "object", "nullable": true, "properties": { "promptId": { "type": "string", "description": "Prompt ID" }, "prompt": { "type": "string", "description": "The prompt text" }, "language": { "type": "string", "description": "Language of the prompt" }, "geolocation": { "type": "string", "description": "Geolocation used for the prompt" } } }, "mentions": { "type": "array", "description": "All entities mentioned in this response", "items": { "type": "object", "properties": { "entityUuid": { "type": "string" }, "entityName": { "type": "string" }, "entityDomain": { "type": "string", "nullable": true }, "position": { "type": "number" }, "sentiment": { "type": "number", "nullable": true }, "isCurrentEntity": { "type": "boolean", "description": "Whether this is the queried entity" } } } }, "citations": { "type": "array", "description": "All URLs cited in this response", "items": { "type": "object", "properties": { "url": { "type": "string" }, "entityUuid": { "type": "string", "description": "Entity UUID associated with this citation" } } } }, "queryFanouts": { "type": "array", "description": "Web search queries the LLM performed while generating this response", "items": { "type": "object", "properties": { "query": { "type": "string" }, "entityUuid": { "type": "string" }, "createdAt": { "type": "string" } } } }, "summary": { "type": "object", "properties": { "mentionsCount": { "type": "number" }, "citationsCount": { "type": "number" }, "queryFanoutsCount": { "type": "number" } } } } } } }, "example": { "success": true, "data": { "response": { "responseId": "2e24732f-a7b4-490b-918d-63ff5cf48683", "responseText": "Here are the top project management tools...", "responseLength": 1250, "createdAt": "2024-01-15T10:30:00.000Z", "modelId": "gpt-4-uuid", "isMentioned": true, "mentionPosition": 2, "mentionSentiment": 0.8, "totalOptionsInList": 5 }, "prompt": { "promptId": "abc123", "prompt": "What are the best project management tools?", "language": "en", "geolocation": "US" }, "mentions": [ { "entityUuid": "entity-uuid-1", "entityName": "Asana", "entityDomain": "asana.com", "position": 1, "sentiment": 0.9, "isCurrentEntity": false }, { "entityUuid": "entity-uuid-2", "entityName": "Monday.com", "entityDomain": "monday.com", "position": 2, "sentiment": 0.8, "isCurrentEntity": true } ], "citations": [ { "url": "https://www.g2.com/categories/project-management", "entityUuid": "g2-entity-uuid" } ], "queryFanouts": [ { "query": "best project management software 2024", "entityUuid": "entity-uuid-2", "createdAt": "2024-01-15T10:29:55.000Z" } ], "summary": { "mentionsCount": 2, "citationsCount": 1, "queryFanoutsCount": 1 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response or entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/models": { "get": { "operationId": "getModels", "summary": "Get Models", "description": "Get all available LLM models.", "tags": [ "Models" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "total": { "type": "number" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trends/visibility": { "get": { "operationId": "getVisibilityTrend", "summary": "Get Visibility Trend", "description": "Get visibility trend over time.", "tags": [ "Analytics" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "14d", "30d" ] }, "description": "Time period" }, { "name": "models", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated model UUIDs" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated tag IDs to filter prompts by" }, { "name": "promptIds", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated prompt IDs to filter by specific prompts" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "score": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trends/sentiment": { "get": { "operationId": "getSentimentTrend", "summary": "Get Sentiment Trend", "description": "Get sentiment trend over time.", "tags": [ "Analytics" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "14d", "30d" ] }, "description": "Time period" }, { "name": "models", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated model UUIDs" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "positive": { "type": "number" }, "neutral": { "type": "number" }, "negative": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trends/citations": { "get": { "operationId": "getCitationsTrend", "summary": "Get Citations Trend", "description": "Get daily citation trend for top cited domains over time. Returns time-series data showing how many times each of the top domains was cited per day, useful for tracking citation patterns and identifying emerging or declining sources.", "tags": [ "Analytics" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "14d", "30d" ] }, "description": "Time period. Defaults to 30d if not specified." }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Custom start date (YYYY-MM-DD). Use with endDate instead of period." }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Custom end date (YYYY-MM-DD). Use with startDate instead of period." }, { "name": "models", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated model UUIDs" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated tag IDs to filter prompts by" }, { "name": "promptIds", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated prompt IDs to filter by specific prompts" }, { "name": "topN", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }, "description": "Number of top cited domains to include in the trend. Defaults to 10, max 20." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "description": "Array of daily data points. Each object has a `day` field (YYYY-MM-DD) plus a key for each top domain name with its citation count for that day.", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "Date in YYYY-MM-DD format" } }, "additionalProperties": { "type": "integer", "description": "Citation count for a domain on this day" } } }, "entities": { "type": "array", "description": "Metadata for each top cited domain included in the trend data.", "items": { "type": "object", "properties": { "entityId": { "type": "string", "nullable": true, "description": "Convex entity ID (if the domain is a tracked entity)" }, "entityUuid": { "type": "string", "description": "Entity UUID" }, "name": { "type": "string", "description": "Domain or entity name" }, "domain": { "type": "string", "nullable": true, "description": "Domain URL" }, "totalCitations": { "type": "integer", "description": "Total citation count for the entire period" } } } }, "period": { "type": "string", "description": "The period used for the query" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/query-fanouts": { "get": { "operationId": "getQueryFanouts", "summary": "Get Query Fanouts", "description": "Get web search queries that LLMs performed during response generation. These are the queries that AI models use to search the web while generating their responses.", "tags": [ "Analytics" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "14d", "30d" ] }, "description": "Time period (default: 30d)" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Start date (ISO format, for custom range)" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "End date (ISO format, for custom range)" }, { "name": "models", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated model UUIDs to filter by" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated tag IDs to filter by" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Results per page (1-100, default: 20)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "number", "default": 0 }, "description": "Pagination offset" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search filter for query text" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string", "description": "The web search query text" }, "frequency": { "type": "number", "description": "Number of times this query was performed" }, "uniqueResponses": { "type": "number", "description": "Number of unique responses that triggered this query" }, "latestDate": { "type": "string", "description": "ISO timestamp of the most recent occurrence" }, "modelIds": { "type": "array", "items": { "type": "string" }, "description": "Model UUIDs that performed this query" } } } }, "totalCount": { "type": "number", "description": "Total number of unique queries" }, "totalQueries": { "type": "number", "description": "Total number of query occurrences" }, "pagination": { "type": "object", "properties": { "totalCount": { "type": "number" }, "totalPages": { "type": "number" }, "currentPage": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } } }, "period": { "type": "string", "description": "The time period used for the query" } } }, "example": { "success": true, "data": [ { "query": "best project management tools 2024", "frequency": 15, "uniqueResponses": 12, "latestDate": "2024-01-15T10:30:00.000Z", "modelIds": [ "uuid-1", "uuid-2" ] }, { "query": "top productivity software reviews", "frequency": 8, "uniqueResponses": 6, "latestDate": "2024-01-14T15:45:00.000Z", "modelIds": [ "uuid-1" ] } ], "totalCount": 150, "totalQueries": 450, "pagination": { "totalCount": 150, "totalPages": 8, "currentPage": 1, "limit": 20, "offset": 0, "hasNextPage": true, "hasPreviousPage": false }, "period": "30d" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/entities/actions": { "get": { "operationId": "getEntityActions", "summary": "Get Actions", "description": "Get AI-generated actionable recommendations and their associated tasks for an entity. Actionables are SEO improvement suggestions generated after each mention check. Tasks are actionables that have been moved to the kanban board for tracking.", "tags": [ "Actions" ], "parameters": [ { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Entity ID" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "dismissed", "in_task" ] }, "description": "Filter actionables by status (default: all)" } ], "responses": { "200": { "description": "Actions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "actionables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Actionable ID" }, "title": { "type": "string", "description": "Actionable title" }, "description": { "type": "string", "description": "Detailed description of the recommendation" }, "category": { "type": "string", "enum": ["problem", "visibility", "citation", "on-page"], "description": "Category of the actionable" }, "priority": { "type": "string", "enum": ["high", "medium", "low"], "description": "Priority level" }, "sourceType": { "type": "string", "description": "Source that generated this actionable (e.g. negative_sentiment, low_visibility)" }, "status": { "type": "string", "enum": ["active", "dismissed", "in_task"], "description": "Current status" }, "metadata": { "type": "object", "nullable": true, "description": "Rich metadata (citation URLs, links, etc.)" }, "createdAt": { "type": "number", "description": "Creation timestamp (ms)" }, "updatedAt": { "type": "number", "description": "Last updated timestamp (ms)" } } } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID" }, "title": { "type": "string", "description": "Task title" }, "description": { "type": "string", "description": "Task description" }, "type": { "type": "string", "enum": ["on-page", "off-page"], "description": "Task type" }, "priority": { "type": "string", "enum": ["high", "medium", "low"], "description": "Priority level" }, "status": { "type": "string", "enum": ["not_started", "in_progress", "in_review", "done"], "description": "Task status on the kanban board" }, "assignees": { "type": "array", "items": { "type": "string" }, "description": "Assigned user IDs" }, "sortOrder": { "type": "number", "nullable": true, "description": "Position within the status column" }, "actionableId": { "type": "string", "nullable": true, "description": "Source actionable ID (if created from one)" }, "createdAt": { "type": "number", "description": "Creation timestamp (ms)" }, "updatedAt": { "type": "number", "description": "Last updated timestamp (ms)" } } } } } }, "counts": { "type": "object", "properties": { "actionables": { "type": "number" }, "tasks": { "type": "number" } } } } }, "example": { "success": true, "data": { "actionables": [ { "id": "abc123", "title": "Improve presence on Reddit r/webdev", "description": "Your brand is rarely mentioned in r/webdev discussions. Consider contributing helpful content to increase visibility.", "category": "citation", "priority": "high", "sourceType": "low_visibility", "status": "active", "metadata": null, "createdAt": 1712345678000, "updatedAt": 1712345678000 } ], "tasks": [ { "id": "task456", "title": "Address negative sentiment on Stack Overflow", "description": "Multiple AI models reference negative reviews. Create documentation to address common issues.", "type": "off-page", "priority": "medium", "status": "in_progress", "assignees": ["user789"], "sortOrder": 0, "actionableId": "abc789", "createdAt": 1712345678000, "updatedAt": 1712345678000 } ] }, "counts": { "actionables": 1, "tasks": 1 } } } } }, "400": { "description": "Bad request — missing entityId parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/entities/actions/dismiss": { "post": { "operationId": "dismissActionable", "summary": "Dismiss Actionable", "description": "Dismiss an actionable recommendation so it no longer appears in the active feed. Dismissed actionables free up slots for new ones to be generated on the next mention check (max 30 active per entity).", "tags": [ "Actions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["actionableId"], "properties": { "actionableId": { "type": "string", "description": "The actionable ID to dismiss" } } } } } }, "responses": { "200": { "description": "Actionable dismissed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Bad request — missing actionableId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/domain-groups": { "get": { "operationId": "listDomainGroups", "summary": "List Domain Groups", "description": "List all domain groups in the workspace. A domain group merges analytics for multiple entities that represent the same brand into a single entry.\n\nProvide the optional `groupId` query parameter to fetch a single group by its ID, or `entityId` to filter to groups scoped to a specific entity tracking.", "tags": [ "Domain Groups" ], "parameters": [ { "name": "groupId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "When provided, returns a single domain group by ID." }, { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "When provided, only returns groups scoped to this entity tracking (or legacy groups that have no tracking scope)." } ], "responses": { "200": { "description": "Domain groups retrieved successfully.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Returned when neither groupId nor an empty result is requested.", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DomainGroup" } }, "count": { "type": "number" } } }, { "type": "object", "description": "Returned when `groupId` is supplied.", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/DomainGroup" } } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain group not found (only when `groupId` is supplied).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfter": { "type": "number" } } } } } } } }, "post": { "operationId": "createDomainGroup", "summary": "Create Domain Group", "description": "Create a domain group that merges analytics for multiple entities representing the same brand.\n\nEntity references in `primaryEntity` and `entities` may be either:\n- an `entityId` returned by `GET /v1/entities` (a tracking ID for an entity in this workspace), or\n- an entity UUID returned as `entityUuid` by `GET /v1/competitors` (any entity in the system).\n\nAt least 2 entities are required, and `primaryEntity` must be included in the `entities` array. Each entity may belong to at most one group at a time. Additional non-primary entities count toward your workspace entity limit.", "tags": [ "Domain Groups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "primaryEntity", "entities" ], "properties": { "name": { "type": "string", "description": "Display name for the group. Defaults to the primary entity's name when omitted." }, "primaryEntity": { "type": "string", "description": "The primary entity reference (entityId or entity UUID). Its name/favicon represent the group in the UI." }, "entities": { "type": "array", "minItems": 2, "items": { "type": "string" }, "description": "Array of 2+ entity references (entityIds or entity UUIDs). Must include the primary entity." }, "entityId": { "type": "string", "description": "Optional. When provided, scopes the group to this entity tracking. Only analytics generated under this tracking will be merged." } } }, "examples": { "merge_brand_domains": { "summary": "Merge two workspace entities", "value": { "name": "Acme", "primaryEntity": "j5712abc34def56ghij7890klmn", "entities": [ "j5712abc34def56ghij7890klmn", "j97def56ghij7890klmn5712abc" ] } }, "merge_with_competitor_uuid": { "summary": "Merge with a competitor entity UUID", "description": "Mix workspace tracking IDs and entity UUIDs from /v1/competitors.", "value": { "primaryEntity": "j5712abc34def56ghij7890klmn", "entities": [ "j5712abc34def56ghij7890klmn", "550e8400-e29b-41d4-a716-446655440000" ] } } } } } }, "responses": { "201": { "description": "Domain group created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/DomainGroup" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request — validation failed, fewer than 2 entities, primary not included, entity overlap with another group, or workspace entity limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Referenced `entityId` not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — either the global write limit or the per-workspace domain-group change limit (5 changes per week).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfter": { "type": "number" } } } } } } } }, "patch": { "operationId": "updateDomainGroup", "summary": "Update Domain Group", "description": "Update an existing domain group. Only the fields provided in the request body are changed.\n\nWhen `entities` is supplied, the same validation rules apply as when creating: at least 2 entities, the primary entity must be a member, entities must not overlap with other groups in the workspace, and the workspace entity limit must not be exceeded.", "tags": [ "Domain Groups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "groupId" ], "properties": { "groupId": { "type": "string", "description": "The ID of the domain group to update." }, "name": { "type": "string", "description": "New display name for the group." }, "primaryEntity": { "type": "string", "description": "New primary entity reference (entityId or entity UUID). Must be present in `entities`." }, "entities": { "type": "array", "minItems": 2, "items": { "type": "string" }, "description": "Replacement set of 2+ entity references." } } }, "examples": { "rename_group": { "summary": "Rename a group", "value": { "groupId": "jh71abc...", "name": "Acme Worldwide" } }, "add_an_entity": { "summary": "Add an entity to the group", "value": { "groupId": "jh71abc...", "entities": [ "j5712abc34def56ghij7890klmn", "j97def56ghij7890klmn5712abc", "550e8400-e29b-41d4-a716-446655440000" ] } } } } } }, "responses": { "200": { "description": "Domain group updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/DomainGroup" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request — validation failed (see message).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfter": { "type": "number" } } } } } } } }, "delete": { "operationId": "deleteDomainGroup", "summary": "Delete Domain Group", "description": "Delete a domain group. Analytics for the previously merged entities will be reported separately again.", "tags": [ "Domain Groups" ], "parameters": [ { "name": "groupId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The ID of the domain group to delete." } ], "responses": { "200": { "description": "Domain group deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request — missing groupId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retryAfter": { "type": "number" } } } } } } } } }, "/entities/actions/update-status": { "post": { "operationId": "updateTaskStatus", "summary": "Update Task Status", "description": "Update the status of a task on the kanban board. Move tasks through the workflow: not_started → in_progress → in_review → done.", "tags": [ "Actions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["taskId", "status"], "properties": { "taskId": { "type": "string", "description": "The task ID to update" }, "status": { "type": "string", "enum": ["not_started", "in_progress", "in_review", "done"], "description": "New status for the task" } } } } } }, "responses": { "200": { "description": "Task status updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Bad request — missing fields or invalid status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }