{ "openapi": "3.1.0", "info": { "title": "Mindshare API", "description": "The Mindshare API provides comprehensive access to brand visibility analytics, customer intelligence, and growth tracking. Use this API to retrieve customer data, query groups, execution results, domain insights, and actionable recommendations for improving your brand's AI visibility.", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.mindshare.so/customer/v1" } ], "security": [ { "apiKeyHeader": [] } ], "paths": { "/get-organization-customers": { "post": { "description": "Retrieve a list of all customers associated with the organization.\n\nThis endpoint provides detailed information including customer account status, trial periods, payment status, and scan schedules.", "requestBody": { "description": "Organization ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationID": { "type": "number", "description": "The ID of the organization" } }, "required": [ "organizationID" ] } } }, "required": true }, "responses": { "200": { "description": "List of customers for the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCustomersResponse" } } } } } } }, "/get-customer-query-groups": { "post": { "description": "Retrieve query groups associated with a customer.\nA query group represents a set of related queries for a specific product line or campaign. Customers can have multiple query groups.\n\nThis endpoint returns keywords, scan location, and a complete history of all scans with their scores and dates.", "requestBody": { "description": "Customer ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerID": { "type": "number", "description": "The ID of the customer" } }, "required": [ "customerID" ] } } }, "required": true }, "responses": { "200": { "description": "List of query groups for the customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryGroupsResponse" } } } } } } }, "/get-queries": { "post": { "description": "This endpoint returns a comprehensive list of queries with complete answer analysis, including whether your customer appears in the answers, the full answer text, competitors mentioned in responses, and all sources cited in the answers.\n\nUse either queryGroupID with a date range for historical data, or executionID to get results from a specific scan.\n\nResults include executions from all supported AI platforms (e.g. ChatGPT, Google AI Overview) by default.", "requestBody": { "description": "Get queries parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerID": { "type": "number", "description": "The ID of the customer" }, "queryGroupID": { "type": "number", "description": "The ID of the query group" }, "startDate": { "type": "string", "format": "date", "description": "Start date in yyyy-mm-dd format" }, "endDate": { "type": "string", "format": "date", "description": "End date in yyyy-mm-dd format" }, "executionID": { "type": "number", "description": "The ID of the execution" }, "aiPlatform": { "type": "string", "description": "Optional. Filter results to a single AI platform. Current values: 'chatgpt' (ChatGPT), 'aioverview' (Google AI Overview). Additional platforms may be added in the future. If omitted, results from all platforms are returned. Not needed when 'executionID' is provided, since an execution already belongs to a single platform." } }, "required": [ "customerID" ] } } }, "required": true }, "responses": { "200": { "description": "List of queries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueriesResponse" } } } } } } }, "/get-companies-stats": { "post": { "description": "This endpoint returns aggregated data showing which companies appear in query results. For each company, you'll receive:\n\nCount: How many queries this company was mentioned in\nPercentage: What percent of total queries this company was mentioned in\n\nUse either queryGroupID with a date range for historical analysis, or executionID to get statistics from a specific scan.\n\nResults include executions from all supported AI platforms (e.g. ChatGPT, Google AI Overview) by default.", "requestBody": { "description": "Get companies stats parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerID": { "type": "number", "description": "The ID of the customer" }, "queryGroupID": { "type": "number", "description": "The ID of the query group" }, "startDate": { "type": "string", "format": "date", "description": "Start date in yyyy-mm-dd format" }, "endDate": { "type": "string", "format": "date", "description": "End date in yyyy-mm-dd format" }, "executionID": { "type": "number", "description": "The ID of the execution" }, "aiPlatform": { "type": "string", "description": "Optional. Filter stats to a single AI platform. Current values: 'chatgpt' (ChatGPT), 'aioverview' (Google AI Overview). Additional platforms may be added in the future. If omitted, stats are aggregated across all platforms. Not needed when 'executionID' is provided, since an execution already belongs to a single platform." } }, "required": [ "customerID" ] } } }, "required": true }, "responses": { "200": { "description": "List of company statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompaniesStatsResponse" } } } } } } }, "/get-domain-stats": { "post": { "description": "This endpoint returns two datasets:\n\n**Domain Stats**: Shows which domains appear in query results\nCount: How many queries this domain was mentioned in\nPercentage: What percent of total queries this domain appeared in\nCategory: Domain category classification\n\n**Article Stats**: Shows which specific articles appear in query results\nCount: How many queries this article was appear in. \nPercentage: What percent of total queries this article appeared in\nisCustomerMentioned: Indicator whether your customer is mentioned inside the article.\n\nResults include executions from all supported AI platforms (e.g. ChatGPT, Google AI Overview) by default.", "requestBody": { "description": "Get domain stats parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerID": { "type": "number", "description": "The ID of the customer" }, "queryGroupID": { "type": "number", "description": "The ID of the query group" }, "startDate": { "type": "string", "format": "date", "description": "Start date in yyyy-mm-dd format" }, "endDate": { "type": "string", "format": "date", "description": "End date in yyyy-mm-dd format" }, "executionID": { "type": "number", "description": "The ID of the execution" }, "aiPlatform": { "type": "string", "description": "Optional. Filter stats to a single AI platform. Current values: 'chatgpt' (ChatGPT), 'aioverview' (Google AI Overview). Additional platforms may be added in the future. If omitted, stats are aggregated across all platforms. Not needed when 'executionID' is provided, since an execution already belongs to a single platform." } }, "required": [ "customerID" ] } } }, "required": true }, "responses": { "200": { "description": "Domain and article statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainStatsResponse" } } } } } } }, "/get-recommendations": { "post": { "description": "Retrieve weekly strategic recommendations for improving brand visibility.\n\nOur system provides data-driven recommendations that help you increase your presence in AI-generated responses. Each recommendation includes:\n\nWhy it's relevant, platform where the recommendation should be executed (Reddit, blog, YouTube, etc.), references to third-party sources currently influencing AI engines, and a direct action URL when applicable.\n\nNote: Google AI Overview is not yet supported here — at the moment all recommendations are generated based on ChatGPT visibility data only.", "requestBody": { "description": "Customer ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerID": { "type": "number", "description": "The ID of the customer" } }, "required": [ "customerID" ] } } }, "required": true }, "responses": { "200": { "description": "List of recommendations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationsResponse" } } } } } } }, "/get-customer-growth-stats": { "post": { "description": "This endpoint provides data organized by query group, with two distinct views:\n\n**Per Scan**: Shows individual scores for each scan with its date. Provides granular, point-in-time data for each scan. Includes execution date and score for each scan\n\n**Overview**: Shows 30-day rolling average scores. Provides smoothed trend data that reduces noise. Calculated as rolling averages based on the last 30 days of executions — computed per AI platform.\n\nResults include executions from all supported AI platforms (e.g. ChatGPT, Google AI Overview) by default.", "requestBody": { "description": "Customer ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerID": { "type": "number", "description": "The ID of the customer" }, "aiPlatform": { "type": "string", "description": "Optional. Filter stats to a single AI platform. Current values: 'chatgpt' (ChatGPT), 'aioverview' (Google AI Overview). Additional platforms may be added in the future. If omitted, stats from all platforms are returned, interleaved in each query group's data array." } }, "required": [ "customerID" ] } } }, "required": true }, "responses": { "200": { "description": "Growth statistics for the customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrowthStatsResponse" } } } } } } }, "/generate-keywords": { "post": { "description": "Generates a list of 10 high-intent SEO keywords for a given website URL in the specified language.\n\nKeywords describe the product or services the website offers without including the business name. For local or niche businesses, keywords include the location or niche within each keyword.\n\nUses AI (GPT) to analyze the website and produce the list.", "requestBody": { "description": "Website URL and language for keyword generation", "content": { "application/json": { "schema": { "type": "object", "properties": { "language": { "type": "string", "description": "The language in which keywords should be generated (case-insensitive). Supported languages: English, Portuguese, Spanish, German, French, Italian, Dutch, Swedish, Polish, Norwegian, Danish, Finnish, Greek, Hungarian, Czech, Romanian, Ukrainian, Slovak, Bulgarian, Croatian, Serbian, Slovenian, Lithuanian, Latvian, Estonian, Icelandic, Belarusian, Bosnian, Albanian, Macedonian, Georgian, Armenian, Azerbaijani, Hindi, Japanese, Korean, Indonesian, Urdu, Bengali, Filipino, Vietnamese, Thai, Burmese, Chinese, Malay, Uzbek, Kazakh, Turkmen, Tajik, Kyrgyz, Sinhala, Khmer, Lao, Hebrew, Arabic, Turkish, Swahili" }, "websiteUrl": { "type": "string", "description": "The website URL to generate keywords for." } }, "required": [ "language", "websiteUrl" ] } } }, "required": true }, "responses": { "200": { "description": "Keywords generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateKeywordsResponse" } } } } } } }, "/create-query-group": { "post": { "description": "Creates a new Query Group for a customer.\n\nA Query Group represents a set of related queries for a specific product line or campaign. Customers can have multiple Query Groups. For example, a cybersecurity company might have separate Query Groups for \"SASE\", \"Network Security\", and \"Endpoint Protection\", each tracking different keywords and AI visibility metrics independently.\n\nQuery Groups allow segmentation of AI visibility across product lines, geographies (e.g., \"UK-focused buying queries\" vs \"US-based comparisons\"), or verticals/use cases (e.g., \"Best AI tools for legal firms\" vs \"Best tools for startups\").\n\nOnce created, the system will begin tracking AI visibility for the provided keywords under this Query Group.\n\n**Note:** Creating a Query Group consumes one credit from the organization's quota.", "requestBody": { "description": "Query Group details", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerID": { "type": "number", "description": "The ID of the customer to create the Query Group for. Must be a valid, existing customer that belongs to the caller's organization." }, "name": { "type": "string", "description": "Display name for the Query Group (e.g., \"SASE\", \"Network Security\"). Must be non-empty." }, "websiteUrl": { "type": "string", "description": "The website URL associated with this Query Group. Does not require http(s):// prefix — bare domains like mindshare.so are valid." }, "keywords": { "type": "string", "description": "Comma-separated list of SEO high-intent keywords to track (e.g., \"residential proxies, rotating proxies, static proxies\"). Each keyword must be non-empty after trimming." }, "language": { "type": "string", "description": "The language for the keywords (case-insensitive). Supported languages: English, Portuguese, Spanish, German, French, Italian, Dutch, Swedish, Polish, Norwegian, Danish, Finnish, Greek, Hungarian, Czech, Romanian, Ukrainian, Slovak, Bulgarian, Croatian, Serbian, Slovenian, Lithuanian, Latvian, Estonian, Icelandic, Belarusian, Bosnian, Albanian, Macedonian, Georgian, Armenian, Azerbaijani, Hindi, Japanese, Korean, Indonesian, Urdu, Bengali, Filipino, Vietnamese, Thai, Burmese, Chinese, Malay, Uzbek, Kazakh, Turkmen, Tajik, Kyrgyz, Sinhala, Khmer, Lao, Hebrew, Arabic, Turkish, Swahili" }, "countryCode": { "type": "string", "description": "Two-letter country code indicating the location context for running queries (e.g., \"us\", \"gb\", \"il\"). Supported codes: us, ca, br, mx, ar, co, cl, pe, ve, ec, bo, uy, pa, cr, do, jm, de, gb, fr, it, es, nl, ch, se, pl, be, at, no, dk, ie, fi, pt, gr, hu, cz, ro, ua, lu, sk, bg, hr, rs, si, lt, lv, ee, is, by, md, ba, al, mk, cy, ge, am, az, im, li, in, jp, kr, id, pk, bd, ph, vn, th, mm, tw, my, hk, sg, uz, kz, tm, tj, kg, lk, kh, la, mo, bn, il, ae, sa, za, ng, eg, tr, iq, qa, kw, om, jo, ma, ke, gh, tz, cm, tn, zw, bw, mz, mw, zm, sl, cg, au, nz" } }, "required": [ "customerID", "name", "websiteUrl", "keywords", "language", "countryCode" ] } } }, "required": true }, "responses": { "200": { "description": "Query Group created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQueryGroupResponse" } } } } } } }, "/create-query-group-from-existing": { "post": { "description": "Creates a new Query Group by cloning an existing one.\n\nA Query Group represents a set of related queries for a specific product line or campaign. Customers can have multiple Query Groups. This endpoint allows duplicating a Query Group's configuration (website URL, keywords, language, country) under a new name, with the option to override any of those fields.\n\nIf the keywords remain the same as the parent, the system clones the existing queries for faster setup. If keywords are changed, the system generates new queries from scratch.\n\nThe parent Query Group must belong to the same customer.\n\n**Note:** Creating a Query Group consumes one credit from the organization's quota.", "requestBody": { "description": "Clone Query Group details", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerID": { "type": "number", "description": "The ID of the customer to create the Query Group for. Must be a valid, existing customer that belongs to the caller's organization." }, "name": { "type": "string", "description": "Display name for the new Query Group. Must be a non-empty string." }, "parentQueryGroupId": { "type": "number", "description": "The ID of the existing Query Group to clone from. Must belong to the same customer, exist, and not be deleted." }, "websiteUrl": { "type": "string", "description": "Override the website URL. If not provided, inherited from the parent Query Group." }, "keywords": { "type": "string", "description": "Override the keywords. Comma-separated list of SEO high-intent keywords (e.g., \"residential proxies, rotating proxies\"). If keywords differ from the parent's, the system generates new queries from scratch rather than cloning existing ones. If not provided, inherited from the parent Query Group." }, "language": { "type": "string", "description": "Override the language (case-insensitive). If not provided, inherited from the parent Query Group. Supported languages: English, Portuguese, Spanish, German, French, Italian, Dutch, Swedish, Polish, Norwegian, Danish, Finnish, Greek, Hungarian, Czech, Romanian, Ukrainian, Slovak, Bulgarian, Croatian, Serbian, Slovenian, Lithuanian, Latvian, Estonian, Icelandic, Belarusian, Bosnian, Albanian, Macedonian, Georgian, Armenian, Azerbaijani, Hindi, Japanese, Korean, Indonesian, Urdu, Bengali, Filipino, Vietnamese, Thai, Burmese, Chinese, Malay, Uzbek, Kazakh, Turkmen, Tajik, Kyrgyz, Sinhala, Khmer, Lao, Hebrew, Arabic, Turkish, Swahili" }, "countryCode": { "type": "string", "description": "Override the two-letter country code for execution location (e.g., \"us\", \"gb\", \"il\"). If not provided, inherited from the parent Query Group. Supported codes: us, ca, br, mx, ar, co, cl, pe, ve, ec, bo, uy, pa, cr, do, jm, de, gb, fr, it, es, nl, ch, se, pl, be, at, no, dk, ie, fi, pt, gr, hu, cz, ro, ua, lu, sk, bg, hr, rs, si, lt, lv, ee, is, by, md, ba, al, mk, cy, ge, am, az, im, li, in, jp, kr, id, pk, bd, ph, vn, th, mm, tw, my, hk, sg, uz, kz, tm, tj, kg, lk, kh, la, mo, bn, il, ae, sa, za, ng, eg, tr, iq, qa, kw, om, jo, ma, ke, gh, tz, cm, tn, zw, bw, mz, mw, zm, sl, cg, au, nz" } }, "required": [ "customerID", "name", "parentQueryGroupId" ] } } }, "required": true }, "responses": { "200": { "description": "Query Group created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQueryGroupResponse" } } } } } } }, "/update-query-group-name": { "post": { "description": "Updates the name of an existing query group.\n\nA query group represents a set of related queries for a specific product line or campaign. Customers can have multiple query groups. The caller must own the query group through their organization.", "requestBody": { "description": "Query Group rename details", "content": { "application/json": { "schema": { "type": "object", "properties": { "queryGroupId": { "type": "number", "description": "The ID of the query group to rename." }, "name": { "type": "string", "description": "The new name for the query group. Must be a non-empty string." } }, "required": [ "queryGroupId", "name" ] } } }, "required": true }, "responses": { "200": { "description": "Query group name updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/update-query-group-status": { "post": { "description": "Updates the status of an existing query group.\n\nA query group represents a set of related queries for a specific product line or campaign. Customers can have multiple query groups. The caller must own the query group through their organization — the system validates that the query group belongs to a customer within the caller's organization.\n\n**Note:** Changing status to **Active** consumes one credit from the organization's quota. Changing status to **Pause** or **Not Active** frees one credit back to the quota.", "requestBody": { "description": "Query Group status update details", "content": { "application/json": { "schema": { "type": "object", "properties": { "queryGroupId": { "type": "number", "description": "The ID of the query group to update." }, "status": { "type": "string", "enum": ["Active", "Not Active", "Pause"], "description": "The new status for the query group." } }, "required": [ "queryGroupId", "status" ] } } }, "required": true }, "responses": { "200": { "description": "Query group status updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/get-queries-definitions": { "post": { "description": "Returns the list of query definitions (prompts) for a given query group.\n\nA query group represents a set of related queries for a specific product line or campaign. This endpoint returns the queries themselves — not execution results. To get execution results with resources, competitors, and scores, use `POST /get-queries` instead.\n\nThe caller must own the query group through their organization.", "requestBody": { "description": "Query Group ID and optional filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "queryGroupId": { "type": "number", "description": "The ID of the query group to retrieve queries for." }, "includeDeleted": { "type": "boolean", "default": false, "description": "If true, includes soft-deleted queries in the response. Defaults to false." } }, "required": [ "queryGroupId" ] } } }, "required": true }, "responses": { "200": { "description": "List of query definitions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueriesDefinitionsResponse" } } } } } } }, "/get-execution-status": { "post": { "description": "Returns the status and progress of a scan execution. Use this to poll whether an execution has completed, track how many queries have been processed, and get an estimated time of completion for in-progress scans.", "requestBody": { "description": "Execution ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "executionID": { "type": "number", "description": "The ID of the execution to check status for." } }, "required": [ "executionID" ] } } }, "required": true }, "responses": { "200": { "description": "Execution status and progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionStatusResponse" } } } } } } }, "/get-organization-quota-status": { "post": { "description": "Returns the organization's query group quota, how many are currently in use, and a per-customer breakdown of active query groups.", "requestBody": { "description": "Organization ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationID": { "type": "number", "description": "The ID of the organization to check quota for. Must match the organization associated with the API key." } }, "required": [ "organizationID" ] } } }, "required": true }, "responses": { "200": { "description": "Organization quota status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationQuotaStatusResponse" } } } } } } }, "/edit-queries-definitions": { "post": { "description": "Adds and/or removes query definitions (prompts) from a query group.\n\nA query group represents a set of related queries for a specific product line or campaign. Customers can have multiple query groups. You can add new queries, remove existing ones, or both in a single call. At least one of `addedQueries` or `deletedQueriesIds` must contain values. The caller must own the query group through their organization.\n\n**Note:** Each query group is limited to a maximum of 150 active (non-deleted) queries.", "requestBody": { "description": "Query definitions to add and/or remove", "content": { "application/json": { "schema": { "type": "object", "properties": { "queryGroupId": { "type": "number", "description": "The ID of the query group to edit." }, "addedQueries": { "type": "array", "items": { "type": "string" }, "description": "List of new query texts to add. Can be an empty array if only deleting." }, "deletedQueriesIds": { "type": "array", "items": { "type": "number" }, "description": "List of query IDs to remove (soft-delete). Can be an empty array if only adding." }, "comments": { "type": "string", "description": "A comment describing the reason for the edit. Stored as part of the version history." } }, "required": [ "queryGroupId", "addedQueries", "deletedQueriesIds" ] } } }, "required": true }, "responses": { "200": { "description": "Query definitions updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } } }, "webhooks": { "/plant/webhook": { "post": { "description": "Information about a new plant added to the store", "requestBody": { "description": "Plant added to the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPlant" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } } } } }, "components": { "schemas": { "Plant": { "required": [ "name" ], "type": "object", "properties": { "name": { "description": "The name of the plant", "type": "string" }, "tag": { "description": "Tag to specify the type", "type": "string" } } }, "NewPlant": { "allOf": [ { "$ref": "#/components/schemas/Plant" }, { "required": [ "id" ], "type": "object", "properties": { "id": { "description": "Identification number of the plant", "type": "integer", "format": "int64" } } } ] }, "Error": { "required": [ "error", "message" ], "type": "object", "properties": { "error": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } }, "Customer": { "type": "object", "properties": { "id": { "type": "number", "description": "Customer ID" }, "name": { "type": "string", "description": "Customer name" }, "created_time": { "type": "string", "format": "date-time", "description": "Customer creation timestamp" }, "trial_start": { "type": "string", "format": "date-time", "description": "Trial start date" }, "trial_end": { "type": "string", "format": "date-time", "description": "Trial end date" }, "last_scan_date": { "type": "string", "format": "date-time", "description": "Last scan date" }, "next_scheduled_run": { "type": "string", "format": "date-time", "nullable": true, "description": "Next scheduled run date" }, "paying_customer": { "type": "boolean", "description": "Whether the customer is a paying customer" }, "website_url": { "type": "string", "format": "uri", "description": "Customer website URL" }, "view_report_url": { "type": "string", "description": "URL to view the customer report" } }, "required": [ "id", "name", "created_time", "trial_start", "trial_end", "last_scan_date", "paying_customer", "website_url", "view_report_url" ] }, "OrganizationCustomersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" }, "description": "List of customers" }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] }, "Execution": { "type": "object", "properties": { "id": { "type": "number", "description": "Execution ID" }, "title": { "type": "string", "description": "Execution title" }, "execution_date": { "type": "string", "format": "date", "description": "Date of execution" }, "score": { "type": "number", "description": "Execution score" }, "ai_platform": { "type": "string", "description": "AI platform this execution ran against. Current values: 'chatgpt' (ChatGPT), 'aioverview' (Google AI Overview). Additional platforms may be added in the future." } }, "required": [ "id", "title", "execution_date", "score", "ai_platform" ] }, "QueryGroup": { "type": "object", "properties": { "query_group_id": { "type": "number", "description": "Query group ID" }, "group_type": { "type": "string", "description": "Type of the group" }, "query_group_name": { "type": "string", "description": "Name of the query group" }, "created_time": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "keywords": { "type": "string", "description": "Keywords for the group" }, "num_of_queries": { "type": "number", "nullable": true, "description": "Number of queries" }, "website_url": { "type": "string", "format": "uri", "description": "Website URL" }, "run_from_location": { "type": "string", "description": "Location to run from. Default is 'us'" }, "executions": { "type": "array", "items": { "$ref": "#/components/schemas/Execution" }, "description": "List of executions" } }, "required": [ "query_group_id", "group_type", "query_group_title", "created_time", "keywords", "website_url", "run_from_location", "executions" ] }, "QueryGroupsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/QueryGroup" }, "description": "List of query groups" }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] }, "Query": { "type": "object", "properties": { "resources_data_path": { "type": "string", "format": "uri", "description": "URL to resources data" }, "date": { "type": "string", "format": "date-time", "description": "Query execution date" }, "is_product_in_results": { "type": "number", "description": "Whether product is in results (0 or 1)" }, "competitors_data_path": { "type": "string", "format": "uri", "description": "URL to competitors full data. The main customer can appear in this list." }, "query": { "type": "string", "description": "The query text" }, "query_id": { "type": "number", "description": "Query ID" }, "execution_id": { "type": "number", "description": "Execution ID" }, "ai_platform": { "type": "string", "description": "AI platform this query result came from. Current values: 'chatgpt' (ChatGPT), 'aioverview' (Google AI Overview). Additional platforms may be added in the future." }, "query_results_path": { "type": "string", "format": "uri", "description": "URL to query results text" } }, "required": [ "resources_data_path", "date", "is_product_in_results", "competitors_data_path", "query", "query_id", "execution_id", "ai_platform", "query_results_path" ] }, "QueriesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Query" }, "description": "List of queries" }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] }, "CompanyStat": { "type": "object", "properties": { "company": { "type": "string", "description": "Company name" }, "count": { "type": "number", "description": "Number of occurrences" }, "percentage": { "type": "number", "description": "Percentage of occurrences" } }, "required": [ "company", "count", "percentage" ] }, "CompaniesStatsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyStat" }, "description": "List of company statistics" }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] }, "DomainStat": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain name" }, "count": { "type": "number", "description": "Number of occurrences" }, "percentage": { "type": "number", "description": "Percentage of occurrences" }, "category": { "type": "string", "nullable": true, "description": "Category of the domain" } }, "required": [ "domain", "count", "percentage" ] }, "ArticleStat": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Article URL" }, "count": { "type": "number", "description": "Number of occurrences" }, "percentage": { "type": "number", "description": "Percentage of occurrences" }, "isCustomerMentioned": { "type": "boolean", "description": "Whether the customer is mentioned in this article" } }, "required": [ "url", "count", "percentage", "isCustomerMentioned" ] }, "DomainStatsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "domainStats": { "type": "array", "items": { "$ref": "#/components/schemas/DomainStat" }, "description": "List of domain statistics" }, "articleStats": { "type": "array", "items": { "$ref": "#/components/schemas/ArticleStat" }, "description": "List of article statistics" } }, "required": [ "domainStats", "articleStats" ] }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] }, "Recommendation": { "type": "object", "properties": { "id": { "type": "number", "description": "Recommendation ID" }, "title": { "type": "string", "description": "Title of the recommendation" }, "task": { "type": "string", "description": "Task description" }, "data_points": { "type": "string", "description": "Data points supporting the recommendation" }, "why_important": { "type": "string", "description": "Why this recommendation is important" }, "platform": { "type": "string", "description": "Platform where the recommendation applies" }, "status": { "type": "string", "description": "Status of the recommendation" }, "date": { "type": "string", "format": "date", "description": "Date of the recommendation" }, "query_group_id": { "type": "number", "description": "ID of the query group" }, "take_action_url": { "type": "string", "format": "uri", "nullable": true, "description": "A direct URL where the user should take action. Present when the recommendation involves engaging with a specific external resource (e.g. a Reddit thread to comment on). Null when the recommendation is a general action without a single target URL." }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/RecommendationReference" }, "description": "A list of existing third-party sources in the customer's niche that are currently influencing AI engines. Provided as context and inspiration — they show what content is already being cited by AI in the customer's space. Returns empty array when no references exist." } }, "required": [ "id", "title", "task", "data_points", "why_important", "platform", "status", "date", "query_group_id", "take_action_url", "references" ] }, "RecommendationReference": { "type": "object", "properties": { "source_id": { "type": "number", "description": "Internal identifier of the source" }, "source_url": { "type": "string", "format": "uri", "description": "The URL of the external source" } }, "required": [ "source_id", "source_url" ] }, "RecommendationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" }, "description": "List of recommendations" }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] }, "PerScanDataPoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Execution date" }, "aiPlatform": { "type": "string", "description": "AI platform this scan ran against. Current values: 'chatgpt' (ChatGPT), 'aioverview' (Google AI Overview). Additional platforms may be added in the future." }, "score": { "type": "number", "description": "Score for this scan" }, "executionId": { "type": "number", "description": "ID of the execution" } }, "required": [ "date", "aiPlatform", "score", "executionId" ] }, "PerScanGroup": { "type": "object", "properties": { "queryGroupId": { "type": "number", "description": "Query group ID" }, "queryGroupTitle": { "type": "string", "description": "Query group title" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PerScanDataPoint" }, "description": "Per scan data points" } }, "required": [ "queryGroupId", "queryGroupTitle", "data" ] }, "OverviewDataPoint": { "type": "object", "properties": { "startDate": { "type": "string", "format": "date", "description": "Start date of the 30-day window" }, "endDate": { "type": "string", "format": "date", "description": "End date of the 30-day window" }, "aiPlatform": { "type": "string", "description": "AI platform this rolling average is computed for. Current values: 'chatgpt' (ChatGPT), 'aioverview' (Google AI Overview). Additional platforms may be added in the future." }, "score": { "type": "number", "description": "Rolling average score for the 30-day period" } }, "required": [ "startDate", "endDate", "aiPlatform", "score" ] }, "OverviewGroup": { "type": "object", "properties": { "queryGroupId": { "type": "number", "description": "Query group ID" }, "queryGroupTitle": { "type": "string", "description": "Query group title" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OverviewDataPoint" }, "description": "Overview data points with 30-day rolling averages" } }, "required": [ "queryGroupId", "queryGroupTitle", "data" ] }, "GrowthStatsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "perScan": { "type": "array", "items": { "$ref": "#/components/schemas/PerScanGroup" }, "description": "Per scan data for each query group" }, "overview": { "type": "array", "items": { "$ref": "#/components/schemas/OverviewGroup" }, "description": "Overview data with 30-day rolling averages for each query group" } }, "required": [ "perScan", "overview" ] }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] }, "GenerateKeywordsResponse": { "type": "object", "properties": { "data": { "type": "string", "description": "Comma-separated list of 10 SEO keywords" }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] }, "CreateQueryGroupResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "query_group_id": { "type": "number", "description": "The ID of the newly created Query Group" } }, "required": [ "query_group_id" ], "description": "Created Query Group details" }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] }, "MessageResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "required": [ "message" ], "description": "Response details" }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] }, "QueryDefinition": { "type": "object", "properties": { "query_id": { "type": "number", "description": "The unique ID of the query" }, "query": { "type": "string", "description": "The query text/prompt" }, "query_group_id": { "type": "number", "description": "The ID of the query group this query belongs to" }, "date": { "type": "string", "format": "date-time", "description": "The last update date of the query" }, "is_deleted": { "type": "number", "description": "Whether the query has been soft-deleted (0 or 1). Only relevant when includeDeleted is true." } }, "required": [ "query_id", "query", "query_group_id", "date", "is_deleted" ] }, "ExecutionProgress": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of queries in the execution" }, "completed": { "type": "number", "description": "Number of queries that have finished processing" } }, "required": [ "total", "completed" ] }, "ExecutionStatusResponse": { "type": "object", "properties": { "status": { "type": "number", "description": "HTTP status code" }, "data": { "type": "object", "properties": { "execution_status": { "type": "string", "enum": ["Done", "In Progress"], "description": "Either \"Done\" or \"In Progress\"" }, "progress": { "$ref": "#/components/schemas/ExecutionProgress" }, "eta_hours": { "type": "number", "nullable": true, "description": "Estimated hours until completion. Null when status is \"Done\" or when ETA cannot be determined." } }, "required": [ "execution_status", "progress", "eta_hours" ] }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "status", "data", "version", "env" ] }, "QuotaCustomer": { "type": "object", "properties": { "customer_id": { "type": "number", "description": "Customer ID" }, "customer_name": { "type": "string", "description": "Customer name" }, "active_query_groups": { "type": "number", "description": "Number of query groups with status \"Active\" for this customer" } }, "required": [ "customer_id", "customer_name", "active_query_groups" ] }, "OrganizationQuotaStatusResponse": { "type": "object", "properties": { "status": { "type": "number", "description": "HTTP status code" }, "data": { "type": "object", "properties": { "quota": { "type": "number", "description": "Maximum number of active query groups allowed for the organization" }, "used": { "type": "number", "description": "Total number of currently active query groups across all customers" }, "customers": { "type": "array", "items": { "$ref": "#/components/schemas/QuotaCustomer" }, "description": "Per-customer breakdown of active query groups. Empty array if no customers exist." } }, "required": [ "quota", "used", "customers" ] }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "status", "data", "version", "env" ] }, "QueriesDefinitionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/QueryDefinition" }, "description": "List of query definitions" }, "version": { "type": "string", "description": "API version" }, "env": { "type": "string", "description": "Environment name" } }, "required": [ "data", "version", "env" ] } }, "securitySchemes": { "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } } }