{ "openapi": "3.1.0", "info": { "title": "Gauge Chat API", "version": "1.0", "description": "The Gauge Chat API: manage tracked prompts and query AI visibility data.\n\n**Authentication:** `Authorization: Bearer ` using either a Gauge CLI\nlogin token (`gauge auth login`) or an organization API key. Login tokens are\nuser-bound; every request is checked against your current organization\nmemberships. API keys act as their organization (and, for an agency, its\nclients), and are scoped to read or read+write. `GET /me` describes the\ntoken in use.\n\n**Conventions:** camelCase JSON; typed opaque string IDs (`prm_…`, `top_…`);\nerrors as `{\"error\": {\"code\", \"message\", \"field\"?}}`; list endpoints page with\nan opaque `cursor` and return `nextCursor`.\n", "contact": { "name": "Gauge support", "email": "support@withgauge.com" } }, "paths": { "/me": { "get": { "operationId": "me", "summary": "Get current credential", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Who this token acts as, and what it may do: a user for a CLI login\ntoken, an organization's API key otherwise.", "tags": [ "Organizations" ] } }, "/orgs": { "get": { "operationId": "listOrgs", "summary": "List organizations", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Every organization this token reaches, with the Gauge products each one\nuses: your memberships, or an API key's organization and its agency\nclients. Organization-scoped Chat routes still answer only for\norganizations whose `products.chat` is true.", "tags": [ "Organizations" ] } }, "/orgs/{org}": { "get": { "operationId": "getOrg", "summary": "Get organization", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryOrganization" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "`org` is an organization slug or UUID; answers even without Chat.", "tags": [ "Organizations" ] } }, "/orgs/{org}/categories": { "get": { "operationId": "listCategories", "summary": "List categories", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Organizations" ] } }, "/orgs/{org}/categories/{category}": { "get": { "operationId": "getCategory", "summary": "Get category", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "`category` is a category slug or `cat_` ID.", "tags": [ "Organizations" ] } }, "/orgs/{org}/categories/{category}/topics": { "get": { "operationId": "listTopics", "summary": "List topics", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true }, { "in": "query", "name": "cursor", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "required": false }, { "in": "query", "name": "limit", "schema": { "default": 50, "title": "Limit", "type": "integer" }, "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Topics" ] }, "post": { "operationId": "createTopic", "summary": "Create topic", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topic" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Topics" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicIn" } } }, "required": true } } }, "/orgs/{org}/categories/{category}/topics/{topic_id}": { "get": { "operationId": "getTopic", "summary": "Get topic", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true }, { "in": "path", "name": "topic_id", "schema": { "title": "Topic Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topic" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Topics" ] }, "patch": { "operationId": "renameTopic", "summary": "Rename topic", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true }, { "in": "path", "name": "topic_id", "schema": { "title": "Topic Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topic" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Renames the topic. Its slug follows the new title.", "tags": [ "Topics" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicIn" } } }, "required": true } } }, "/orgs/{org}/categories/{category}/prompts": { "get": { "operationId": "listPrompts", "summary": "List prompts", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true }, { "in": "query", "name": "topic", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topic" }, "required": false }, { "in": "query", "name": "tag", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tag" }, "required": false }, { "in": "query", "name": "trackingType", "schema": { "default": "all", "enum": [ "visibility", "branded_own", "all" ], "title": "Trackingtype", "type": "string" }, "required": false }, { "in": "query", "name": "cursor", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "required": false }, { "in": "query", "name": "limit", "schema": { "default": 50, "title": "Limit", "type": "integer" }, "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Prompts" ] }, "post": { "operationId": "createPrompts", "summary": "Create prompts", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true }, { "in": "query", "name": "dryRun", "schema": { "default": false, "title": "Dryrun", "type": "boolean" }, "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptsOut" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptsOut" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Create prompts in bulk and queue them for sampling.\n\nA prompt whose text matches an existing prompt in the category (ignoring\ncase and whitespace) is returned as `already_exists`, so retries are safe.\nIf the new prompts exceed the plan's prompt limit, nothing is created and\nthe response is 403 `limit_exceeded`.", "tags": [ "Prompts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptsIn" } } }, "required": true } }, "patch": { "operationId": "updatePrompts", "summary": "Bulk update prompts", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPatchOut" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Move up to 500 prompts to a topic and/or set their tracking type. IDs\nnot in the category are reported in `notFound`.", "tags": [ "Prompts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPromptPatch" } } }, "required": true } } }, "/orgs/{org}/categories/{category}/prompts/tags": { "post": { "operationId": "addPromptTags", "summary": "Add tags to prompts", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptTagsOut" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Apply every tag in `tagIds` to every prompt in `promptIds`.", "tags": [ "Prompts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptTagsIn" } } }, "required": true } }, "delete": { "operationId": "removePromptTags", "summary": "Remove tags from prompts", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptTagsOut" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Remove every tag in `tagIds` from every prompt in `promptIds`.", "tags": [ "Prompts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptTagsIn" } } }, "required": true } } }, "/orgs/{org}/categories/{category}/prompts/{prompt_id}": { "get": { "operationId": "getPrompt", "summary": "Get prompt", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true }, { "in": "path", "name": "prompt_id", "schema": { "title": "Prompt Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptOut" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Prompts" ] }, "patch": { "operationId": "updatePrompt", "summary": "Update prompt", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true }, { "in": "path", "name": "prompt_id", "schema": { "title": "Prompt Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptOut" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Move a prompt to another topic or change its tracking type. Prompt\ntext is immutable: create a new prompt instead.", "tags": [ "Prompts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptPatch" } } }, "required": true } } }, "/orgs/{org}/tags": { "get": { "operationId": "listTags", "summary": "List tags", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Tags" ] }, "post": { "operationId": "createTag", "summary": "Create tag", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Tags" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagIn" } } }, "required": true } } }, "/orgs/{org}/tags/{tag_id}": { "get": { "operationId": "getTag", "summary": "Get tag", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "tag_id", "schema": { "title": "Tag Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Tags" ] }, "patch": { "operationId": "updateTag", "summary": "Update tag", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "tag_id", "schema": { "title": "Tag Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Tags" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagPatch" } } }, "required": true } }, "delete": { "operationId": "deleteTag", "summary": "Delete tag", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "tag_id", "schema": { "title": "Tag Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Deletes the tag and removes it from every prompt.", "tags": [ "Tags" ] } }, "/orgs/{org}/categories/{category}/brands": { "get": { "operationId": "listBrands", "summary": "List brands", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Your owned brands and the category's tracked competitors. Together these\nare the share-of-voice denominator.", "tags": [ "Brands" ] } }, "/orgs/{org}/query": { "post": { "operationId": "query", "summary": "Run a report query", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryOut" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Query a dataset with server-defined metrics. See `query/metadata` for\nwhat each dataset supports.", "tags": [ "Query" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryIn" } } }, "required": true } } }, "/orgs/{org}/query/metadata": { "get": { "operationId": "queryMetadata", "summary": "Get the query catalog", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "query", "name": "dataset", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset" }, "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response", "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "The query catalog, plus values valid for this organization.", "tags": [ "Query" ] } }, "/orgs/{org}/categories/{category}/answers": { "get": { "operationId": "listAnswers", "summary": "List answers", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true }, { "in": "query", "name": "since", "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Defaults to 7 days ago.", "title": "Since" }, "required": false, "description": "Defaults to 7 days ago." }, { "in": "query", "name": "until", "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Defaults to today.", "title": "Until" }, "required": false, "description": "Defaults to today." }, { "in": "query", "name": "model", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Model" }, "required": false }, { "in": "query", "name": "prompt", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Prompt" }, "required": false }, { "in": "query", "name": "topic", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Topic" }, "required": false }, { "in": "query", "name": "tag", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tag" }, "required": false }, { "in": "query", "name": "trackingType", "schema": { "default": "visibility", "enum": [ "visibility", "branded_own", "all" ], "title": "Trackingtype", "type": "string" }, "required": false }, { "in": "query", "name": "cursor", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "required": false }, { "in": "query", "name": "limit", "schema": { "default": 50, "title": "Limit", "type": "integer" }, "required": false }, { "in": "query", "name": "brand", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Only answers mentioning any of these brands.", "title": "Brand" }, "required": false, "description": "Only answers mentioning any of these brands." }, { "in": "query", "name": "brandAbsent", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Only answers mentioning none of these brands.", "title": "Brandabsent" }, "required": false, "description": "Only answers mentioning none of these brands." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Answers" ] } }, "/orgs/{org}/categories/{category}/answers/{answer_id}": { "get": { "operationId": "getAnswer", "summary": "Get answer", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true }, { "in": "path", "name": "answer_id", "schema": { "title": "Answer Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerDetail" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "One answer with its brand mentions, cited pages, and search queries.", "tags": [ "Answers" ] } }, "/orgs/{org}/categories/{category}/citations": { "get": { "operationId": "listCitations", "summary": "List citations", "parameters": [ { "in": "path", "name": "org", "schema": { "title": "Org", "type": "string" }, "required": true }, { "in": "path", "name": "category", "schema": { "title": "Category", "type": "string" }, "required": true }, { "in": "query", "name": "since", "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Defaults to 7 days ago.", "title": "Since" }, "required": false, "description": "Defaults to 7 days ago." }, { "in": "query", "name": "until", "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Defaults to today.", "title": "Until" }, "required": false, "description": "Defaults to today." }, { "in": "query", "name": "model", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Model" }, "required": false }, { "in": "query", "name": "prompt", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Prompt" }, "required": false }, { "in": "query", "name": "topic", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Topic" }, "required": false }, { "in": "query", "name": "tag", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tag" }, "required": false }, { "in": "query", "name": "trackingType", "schema": { "default": "visibility", "enum": [ "visibility", "branded_own", "all" ], "title": "Trackingtype", "type": "string" }, "required": false }, { "in": "query", "name": "cursor", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "required": false }, { "in": "query", "name": "limit", "schema": { "default": 50, "title": "Limit", "type": "integer" }, "required": false }, { "in": "query", "name": "domain", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Domain" }, "required": false }, { "in": "query", "name": "page", "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Page" }, "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitationList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Answers" ] } } }, "components": { "schemas": { "APIKeyInfo": { "properties": { "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "prefix": { "title": "Prefix", "type": "string" }, "organization": { "$ref": "#/components/schemas/Organization" } }, "required": [ "id", "name", "prefix", "organization" ], "title": "APIKeyInfo", "type": "object" }, "Me": { "properties": { "user": { "anyOf": [ { "$ref": "#/components/schemas/UserInfo" }, { "type": "null" } ] }, "apiKey": { "anyOf": [ { "$ref": "#/components/schemas/APIKeyInfo" }, { "type": "null" } ] }, "token": { "$ref": "#/components/schemas/TokenInfo" } }, "required": [ "user", "apiKey", "token" ], "title": "Me", "type": "object" }, "Organization": { "properties": { "id": { "title": "Id", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "slug", "name" ], "title": "Organization", "type": "object" }, "TokenInfo": { "properties": { "kind": { "enum": [ "session", "api_key" ], "title": "Kind", "type": "string" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" } }, "required": [ "kind", "scopes", "expiresAt" ], "title": "TokenInfo", "type": "object" }, "UserInfo": { "properties": { "id": { "title": "Id", "type": "string" }, "email": { "title": "Email", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "email", "name" ], "title": "UserInfo", "type": "object" }, "ErrorDetail": { "properties": { "code": { "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Field" } }, "required": [ "code", "message" ], "title": "ErrorDetail", "type": "object" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "error" ], "title": "ErrorResponse", "type": "object" }, "DirectoryOrganization": { "properties": { "id": { "title": "Id", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "name": { "title": "Name", "type": "string" }, "products": { "$ref": "#/components/schemas/OrganizationProducts" } }, "required": [ "id", "slug", "name", "products" ], "title": "DirectoryOrganization", "type": "object" }, "OrganizationList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DirectoryOrganization" }, "title": "Data", "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" } }, "required": [ "data" ], "title": "OrganizationList", "type": "object" }, "OrganizationProducts": { "properties": { "chat": { "title": "Chat", "type": "boolean" }, "agents": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Agents" } }, "required": [ "chat", "agents" ], "title": "OrganizationProducts", "type": "object" }, "Category": { "properties": { "id": { "title": "Id", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "name": { "title": "Name", "type": "string" }, "description": { "title": "Description", "type": "string" } }, "required": [ "id", "slug", "name", "description" ], "title": "Category", "type": "object" }, "CategoryList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Category" }, "title": "Data", "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" } }, "required": [ "data" ], "title": "CategoryList", "type": "object" }, "Topic": { "properties": { "id": { "title": "Id", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "title": { "title": "Title", "type": "string" }, "promptCount": { "title": "Promptcount", "type": "integer" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" } }, "required": [ "id", "slug", "title", "promptCount", "createdAt" ], "title": "Topic", "type": "object" }, "TopicList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Topic" }, "title": "Data", "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" } }, "required": [ "data" ], "title": "TopicList", "type": "object" }, "TopicIn": { "properties": { "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "TopicIn", "type": "object" }, "PromptListFilters": { "properties": { "topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topic" }, "tag": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tag" }, "trackingType": { "default": "all", "enum": [ "visibility", "branded_own", "all" ], "title": "Trackingtype", "type": "string" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "limit": { "default": 50, "title": "Limit", "type": "integer" } }, "title": "PromptListFilters", "type": "object" }, "PromptList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PromptOut" }, "title": "Data", "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" } }, "required": [ "data" ], "title": "PromptList", "type": "object" }, "PromptOut": { "properties": { "id": { "title": "Id", "type": "string" }, "text": { "title": "Text", "type": "string" }, "topicId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topicid" }, "trackingType": { "title": "Trackingtype", "type": "string" }, "tagIds": { "items": { "type": "string" }, "title": "Tagids", "type": "array" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "firstAnswerDay": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Pacific date of the prompt's first answer; null until sampled.", "title": "Firstanswerday" } }, "required": [ "id", "text", "topicId", "trackingType", "tagIds", "createdAt", "firstAnswerDay" ], "title": "PromptOut", "type": "object" }, "CreatePromptsOut": { "properties": { "results": { "items": { "$ref": "#/components/schemas/CreateResult" }, "title": "Results", "type": "array" }, "dryRun": { "title": "Dryrun", "type": "boolean" }, "remaining": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Prompts still allowed by the plan after this request; null if unlimited.", "title": "Remaining" } }, "required": [ "results", "dryRun", "remaining" ], "title": "CreatePromptsOut", "type": "object" }, "CreateResult": { "properties": { "index": { "title": "Index", "type": "integer" }, "status": { "enum": [ "created", "already_exists", "would_create" ], "title": "Status", "type": "string" }, "prompt": { "anyOf": [ { "$ref": "#/components/schemas/PromptOut" }, { "type": "null" } ] } }, "required": [ "index", "status" ], "title": "CreateResult", "type": "object" }, "CreatePromptsIn": { "properties": { "prompts": { "items": { "$ref": "#/components/schemas/PromptIn" }, "maxItems": 500, "minItems": 1, "title": "Prompts", "type": "array" } }, "required": [ "prompts" ], "title": "CreatePromptsIn", "type": "object" }, "PromptIn": { "properties": { "text": { "maxLength": 500, "minLength": 1, "title": "Text", "type": "string" }, "topicId": { "title": "Topicid", "type": "string" }, "trackingType": { "default": "visibility", "enum": [ "visibility", "branded_own" ], "title": "Trackingtype", "type": "string" }, "tagIds": { "items": { "type": "string" }, "title": "Tagids", "type": "array" } }, "required": [ "text", "topicId" ], "title": "PromptIn", "type": "object" }, "BulkPatchOut": { "properties": { "updated": { "items": { "type": "string" }, "title": "Updated", "type": "array" }, "notFound": { "items": { "type": "string" }, "title": "Notfound", "type": "array" } }, "required": [ "updated", "notFound" ], "title": "BulkPatchOut", "type": "object" }, "BulkPromptPatch": { "properties": { "topicId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topicid" }, "trackingType": { "anyOf": [ { "enum": [ "visibility", "branded_own" ], "type": "string" }, { "type": "null" } ], "title": "Trackingtype" }, "ids": { "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "title": "Ids", "type": "array" } }, "required": [ "ids" ], "title": "BulkPromptPatch", "type": "object" }, "PromptTagsOut": { "properties": { "promptIds": { "items": { "type": "string" }, "title": "Promptids", "type": "array" } }, "required": [ "promptIds" ], "title": "PromptTagsOut", "type": "object" }, "PromptTagsIn": { "properties": { "promptIds": { "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "title": "Promptids", "type": "array" }, "tagIds": { "items": { "type": "string" }, "maxItems": 50, "minItems": 1, "title": "Tagids", "type": "array" } }, "required": [ "promptIds", "tagIds" ], "title": "PromptTagsIn", "type": "object" }, "PromptPatch": { "properties": { "topicId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topicid" }, "trackingType": { "anyOf": [ { "enum": [ "visibility", "branded_own" ], "type": "string" }, { "type": "null" } ], "title": "Trackingtype" } }, "title": "PromptPatch", "type": "object" }, "Tag": { "properties": { "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "color": { "title": "Color", "type": "string" }, "promptCount": { "title": "Promptcount", "type": "integer" } }, "required": [ "id", "name", "color", "promptCount" ], "title": "Tag", "type": "object" }, "TagList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Tag" }, "title": "Data", "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" } }, "required": [ "data" ], "title": "TagList", "type": "object" }, "TagIn": { "properties": { "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "color": { "default": "", "maxLength": 20, "title": "Color", "type": "string" } }, "required": [ "name" ], "title": "TagIn", "type": "object" }, "TagPatch": { "properties": { "name": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "color": { "anyOf": [ { "maxLength": 20, "type": "string" }, { "type": "null" } ], "title": "Color" } }, "title": "TagPatch", "type": "object" }, "BrandList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BrandOut" }, "title": "Data", "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" } }, "required": [ "data" ], "title": "BrandList", "type": "object" }, "BrandOut": { "properties": { "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "website": { "title": "Website", "type": "string" }, "role": { "enum": [ "owned", "competitor" ], "title": "Role", "type": "string" } }, "required": [ "id", "name", "slug", "website", "role" ], "title": "BrandOut", "type": "object" }, "Column": { "properties": { "key": { "title": "Key", "type": "string" }, "kind": { "enum": [ "dimension", "metric" ], "title": "Kind", "type": "string" }, "type": { "title": "Type", "type": "string" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unit" } }, "required": [ "key", "kind", "type" ], "title": "Column", "type": "object" }, "DateRangeOut": { "properties": { "since": { "title": "Since", "type": "string" }, "until": { "title": "Until", "type": "string" } }, "required": [ "since", "until" ], "title": "DateRangeOut", "type": "object" }, "FreshnessOut": { "properties": { "watermark": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Watermark" }, "pending": { "title": "Pending", "type": "integer" }, "available": { "title": "Available", "type": "boolean" } }, "required": [ "watermark", "pending", "available" ], "title": "FreshnessOut", "type": "object" }, "QueryOut": { "properties": { "columns": { "items": { "$ref": "#/components/schemas/Column" }, "title": "Columns", "type": "array" }, "rows": { "items": { "additionalProperties": true, "type": "object" }, "title": "Rows", "type": "array" }, "labels": { "additionalProperties": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, "title": "Labels", "type": "object" }, "dateRange": { "$ref": "#/components/schemas/DateRangeOut" }, "truncated": { "title": "Truncated", "type": "boolean" }, "cached": { "title": "Cached", "type": "boolean" }, "freshness": { "$ref": "#/components/schemas/FreshnessOut" } }, "required": [ "columns", "rows", "labels", "dateRange", "truncated", "cached", "freshness" ], "title": "QueryOut", "type": "object" }, "DateRangeIn": { "additionalProperties": false, "properties": { "since": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD, or a window like `30d`.", "title": "Since" }, "until": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD, inclusive. Defaults to the freshness watermark.", "title": "Until" }, "lastDays": { "anyOf": [ { "maximum": 400, "minimum": 1, "type": "integer" }, { "type": "null" } ], "title": "Lastdays" } }, "title": "DateRangeIn", "type": "object" }, "OrderByIn": { "additionalProperties": false, "properties": { "key": { "title": "Key", "type": "string" }, "dir": { "default": "desc", "enum": [ "asc", "desc" ], "title": "Dir", "type": "string" } }, "required": [ "key" ], "title": "OrderByIn", "type": "object" }, "QueryFilters": { "additionalProperties": false, "properties": { "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category slug or `cat_` ID.", "title": "Category" }, "brand": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Brand" }, "model": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Model" }, "topic": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Topic" }, "tag": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tag" }, "tagMode": { "default": "any", "enum": [ "any", "all" ], "title": "Tagmode", "type": "string" }, "prompt": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Prompt" }, "trackingType": { "default": "visibility", "description": "Prompt tracking type. Defaults to visibility, like the web app.", "enum": [ "visibility", "branded_own", "all" ], "title": "Trackingtype", "type": "string" }, "domain": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Domain" }, "page": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Page" } }, "title": "QueryFilters", "type": "object" }, "QueryIn": { "additionalProperties": false, "properties": { "dataset": { "enum": [ "answers", "citations", "searchQueries", "aiTraffic" ], "title": "Dataset", "type": "string" }, "dimensions": { "items": { "type": "string" }, "maxItems": 3, "title": "Dimensions", "type": "array" }, "metrics": { "items": { "type": "string" }, "maxItems": 4, "minItems": 1, "title": "Metrics", "type": "array" }, "filters": { "allOf": [ { "$ref": "#/components/schemas/QueryFilters" } ] }, "where": { "items": { "$ref": "#/components/schemas/WhereIn" }, "maxItems": 10, "title": "Where", "type": "array" }, "dateRange": { "allOf": [ { "$ref": "#/components/schemas/DateRangeIn" } ] }, "granularity": { "default": "day", "enum": [ "hour", "day", "week", "month" ], "title": "Granularity", "type": "string" }, "orderBy": { "items": { "$ref": "#/components/schemas/OrderByIn" }, "maxItems": 4, "title": "Orderby", "type": "array" }, "limit": { "default": 50, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, "required": [ "dataset", "metrics" ], "title": "QueryIn", "type": "object" }, "WhereIn": { "additionalProperties": false, "properties": { "dimension": { "title": "Dimension", "type": "string" }, "op": { "enum": [ "eq", "neq", "in", "notIn", "contains" ], "title": "Op", "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ], "title": "Value" } }, "required": [ "dimension", "op", "value" ], "title": "WhereIn", "type": "object" }, "AnswerFilters": { "properties": { "since": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Defaults to 7 days ago.", "title": "Since" }, "until": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Defaults to today.", "title": "Until" }, "model": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Model" }, "prompt": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Prompt" }, "topic": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Topic" }, "tag": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tag" }, "trackingType": { "default": "visibility", "enum": [ "visibility", "branded_own", "all" ], "title": "Trackingtype", "type": "string" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "limit": { "default": 50, "title": "Limit", "type": "integer" }, "brand": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Only answers mentioning any of these brands.", "title": "Brand" }, "brandAbsent": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Only answers mentioning none of these brands.", "title": "Brandabsent" } }, "title": "AnswerFilters", "type": "object" }, "AnswerItem": { "properties": { "id": { "title": "Id", "type": "string" }, "promptId": { "title": "Promptid", "type": "string" }, "topicId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topicid" }, "model": { "title": "Model", "type": "string" }, "day": { "format": "date", "title": "Day", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "text": { "title": "Text", "type": "string" }, "brandIds": { "items": { "type": "string" }, "title": "Brandids", "type": "array" } }, "required": [ "id", "promptId", "topicId", "model", "day", "createdAt", "text", "brandIds" ], "title": "AnswerItem", "type": "object" }, "AnswerList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AnswerItem" }, "title": "Data", "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" } }, "required": [ "data" ], "title": "AnswerList", "type": "object" }, "AnswerDetail": { "properties": { "id": { "title": "Id", "type": "string" }, "promptId": { "title": "Promptid", "type": "string" }, "promptText": { "title": "Prompttext", "type": "string" }, "topicId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topicid" }, "model": { "title": "Model", "type": "string" }, "day": { "format": "date", "title": "Day", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "text": { "title": "Text", "type": "string" }, "mentions": { "items": { "$ref": "#/components/schemas/Mention" }, "title": "Mentions", "type": "array" }, "citations": { "items": { "$ref": "#/components/schemas/CitedPage" }, "title": "Citations", "type": "array" }, "searchQueries": { "items": { "type": "string" }, "title": "Searchqueries", "type": "array" } }, "required": [ "id", "promptId", "promptText", "topicId", "model", "day", "createdAt", "text", "mentions", "citations", "searchQueries" ], "title": "AnswerDetail", "type": "object" }, "CitedPage": { "properties": { "pageId": { "title": "Pageid", "type": "string" }, "url": { "title": "Url", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "domain": { "title": "Domain", "type": "string" } }, "required": [ "pageId", "url", "title", "domain" ], "title": "CitedPage", "type": "object" }, "Mention": { "properties": { "brandId": { "title": "Brandid", "type": "string" }, "name": { "title": "Name", "type": "string" }, "mentionTypes": { "items": { "type": "string" }, "title": "Mentiontypes", "type": "array" }, "count": { "title": "Count", "type": "integer" } }, "required": [ "brandId", "name", "mentionTypes", "count" ], "title": "Mention", "type": "object" }, "CitationFilters": { "properties": { "since": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Defaults to 7 days ago.", "title": "Since" }, "until": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Defaults to today.", "title": "Until" }, "model": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Model" }, "prompt": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Prompt" }, "topic": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Topic" }, "tag": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tag" }, "trackingType": { "default": "visibility", "enum": [ "visibility", "branded_own", "all" ], "title": "Trackingtype", "type": "string" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "limit": { "default": 50, "title": "Limit", "type": "integer" }, "domain": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Domain" }, "page": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Page" } }, "title": "CitationFilters", "type": "object" }, "CitationItem": { "properties": { "answerId": { "title": "Answerid", "type": "string" }, "pageId": { "title": "Pageid", "type": "string" }, "promptId": { "title": "Promptid", "type": "string" }, "model": { "title": "Model", "type": "string" }, "day": { "format": "date", "title": "Day", "type": "string" }, "domain": { "title": "Domain", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "answerId", "pageId", "promptId", "model", "day", "domain", "url" ], "title": "CitationItem", "type": "object" }, "CitationList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CitationItem" }, "title": "Data", "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" } }, "required": [ "data" ], "title": "CitationList", "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "gauge_sk_", "description": "An organization API key from **Settings → Integrations → API Keys**, or a Gauge CLI login token from `gauge auth login`." } } }, "servers": [ { "url": "https://app.withgauge.com/api/v1", "description": "Production" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Organizations", "description": "The current credential, and the organizations and categories it reaches." }, { "name": "Topics", "description": "Topics group tracked prompts within a category." }, { "name": "Prompts", "description": "Tracked prompts, their topics, tracking type, and tags." }, { "name": "Tags", "description": "Organization-wide labels for prompts." }, { "name": "Brands", "description": "Brands Gauge tracks in a category, including competitors." }, { "name": "Query", "description": "Aggregate AI visibility reports." }, { "name": "Answers", "description": "Individual AI answers and the citations in them." } ] }