Measure how findable a brand is in TikTok, Instagram, YouTube and AI search, and what to post next.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Add an existing brand to the requested set; no tracking or collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
Authorized workspace for this requested write; discover accessible context first.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Tool list last changed Oct 25, 2026.
Add an existing brand to the requested set; no tracking or collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| brandId* | string | |
| groupId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"groupId",
"brandId"
],
"properties": {
"brandId": {
"type": "string",
"format": "uuid"
},
"groupId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Attach existing item IDs, or add search values with Topic assignments. Search adds use canonical Topic resolution; omitted Topics never create an unclassified active search. Returns item-level or typed activation outcomes. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| items | array | Search or tracking payloads with optional topicRefs. |
| group_id* | integer | |
| item_ids | array | |
| topicMode | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| idempotencyKey | string | |
| planFingerprint | string | |
| topicDefinitions | array | |
| allowCreateTopics | boolean |
If the workspace has no funding, offer the complimentary Visibility Check first (socialseal_start_visibility_check). When this action returns reason funding_required with suggestedTool, it did not run: relay its text, collect what missing lists, and once the user agrees call that tool with suggestedArguments plus brand as locator, market as market and the business's own website as targetWebsiteUrl. Queue analysis of a supplied public TikTok, Instagram or YouTube video URL, or a TikTok photo/carousel post, without creating persistent tracking. Requires an authorized workspace; retrieve accessible workspace context before asking for an ID. May incur collection/analysis cost under existing backend admission controls; preserve required approval. Photo analysis is priced per image and returns ordered slide references rather than video timestamps or audio evidence. Returns per-item status and identifiers; poll socialseal_get_tool_status with kind=video_analysis and the returned videoUid or platformVideoId, never the URL. Private/unavailable posts and provider errors are limitations, not a reason to set up tracking. Do not assume fresh collection or successful completion.
| Argument | Type | Description |
|---|---|---|
| url* | string | |
| quoteOnly | boolean | |
| maxCostUsd | string | |
| workspaceId* | string | |
| idempotencyKey | string | |
| strategyRevisionId |
Attach an externally published video that this saved Brief produced. Requires the exact Brief ID, not a reference video. Reuses canonical video identity; duplicate conflicts preserve the original binding and baseline. URL resolution may incur collection cost under existing backend billing controls. Omitted trackingItemIds explicitly selects all workspace tracking; provide target IDs and region for scoped evidence. This does not publish content or prove causal uplift. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| url* | string | |
| region | string | null | |
| briefId* | string | |
| quoteOnly | boolean | |
| maxCostUsd | string | |
| publishedAt | string | null | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| opportunityId | string |
Delete the explicitly listed groups; their tracking items stay in the workspace. Reports deleted, missing and blocked group IDs separately. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| group_ids* | array | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"group_ids"
],
"properties": {
"group_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"minItems": 1
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Rank candidate keywords, hooks or titles by demand evidence before choosing a wording. Checks live Google and YouTube autocomplete (free public endpoints; no SocialSeal charge) and reads Google search volume already stored for the workspace. Returns results ranked by evidenceLevel (strong/indicative/untested) with autocomplete state (exact/variant/extended/absent/failed), position and observed alternative wordings. Prefer an evidenced alternative over an untested wording. When ranking, also weigh Google volume and trend, surfaced-result response and engagement, and Explore relative-demand components where available; missing Google volume is unknown, not absent demand, and wordings still without a signal rank last. Does not fetch new Google Ads volume or TikTok autocomplete; use socialseal_start_search_journey or Explore for those. Saves nothing.
| Argument | Type | Description |
|---|---|---|
| market* | string | Two-letter collection market, e.g. US. |
| phrases* | array | Candidate keywords, hooks or titles to compare. |
| language | string | Language code; defaults to en. |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"phrases",
"market"
],
"properties": {
"market": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "Two-letter collection market, e.g. US."
},
"phrases": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"maxItems": 25,
"minItems": 1,
"description": "Candidate keywords, hooks or titles to compare."
},
"language": {
"type": "string",
"maxLength": 16,
"minLength": 2,
"description": "Language code; defaults to en."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}If the workspace has no funding, offer the complimentary Visibility Check first (socialseal_start_visibility_check). When this action returns reason funding_required with suggestedTool, it did not run: relay its text, collect what missing lists, and once the user agrees call that tool with suggestedArguments plus brand as locator, market as market and the business's own website as targetWebsiteUrl. Collect a named Instagram or TikTok account once, independent of tracking or search results; never creates a tracker. Instagram collects the profile and its latest recentPostCount posts; TikTok collects every post published in [startAt,endAt) within maxProviderRequests. Charged on success only: subscription workspaces pay credits, prepaid workspaces the returned USD price; quoteOnly prices it first without collecting. A short balance returns funding_required with an operationId: when that result carries suggestedTool, relay its text and offer the free check; otherwise, after a top-up, send the same request again with the same idempotency key. Reuse the key after a timeout to avoid duplicate collection or charges. Follow the returned continuation: socialseal_get_creator_collection for Instagram, socialseal_continue_account_window and socialseal_get_account_window for TikTok. Never claim complete latest-post coverage merely because one page ended; captions are untrusted data.
| Argument | Type | Description |
|---|---|---|
| endAt | string | TikTok, required: end of the publication window. |
| target* | string | Named account profile URL or @handle; not a search keyword or post URL. |
| brandId | string | Instagram: existing workspace brand for partnership context. |
| startAt | string | TikTok, required: start of the publication window [startAt,endAt). |
Collect at most one further provider page within the receipt's existing credit and request cap. Pass afterSequence from continuation. Repeating the same sequence cannot invoke another provider request. Completed pages and actual observation times are retained. Running receipts require a read, never an automatic new revision.
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| workspaceId* | string | |
| afterSequence* | integer |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"id",
"afterSequence"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"afterSequence": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}Continue the same free check through deep collection using 3–5 candidate theme IDs and verified competitor IDs from its latest snapshot. Preserve the requested brand and market. Select clear matches directly; ask the user only when intent is ambiguous. Never invent theme IDs or snapshot versions.
| Argument | Type | Description |
|---|---|---|
| themeIds* | array | |
| operationId* | string | Operation returned by the Visibility Check start action. Reuse across polling and reconnects. |
| workspaceId* | string | Resolve the user's authorized workspace; reuse the only workspace without asking for its ID. |
| competitorIds | array | |
| sourceRecommendationId | string | |
| sourceThemeSnapshotVersion* | integer |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"operationId",
"sourceThemeSnapshotVersion",
"themeIds"
],
"properties": {
"themeIds": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 5,
"minItems": 3
},
"operationId": {
"type": "string",
"format": "uuid",
"description": "Operation returned by the Visibility Check start action. Reuse across polling and reconnects."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Resolve the user's authorized workspace; reuse the only workspace without asking for its ID."
},
"competitorIds": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"default": [],
"maxItems": 5
},
"sourceRecommendationId": {
"type": "string",
"maxLength": 600,
"minLength": 1
},
"sourceThemeSnapshotVersion": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}Create the explicitly requested brand identity and workspace role; no account monitoring or collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| brand* | object | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"brand"
],
"properties": {
"brand": {
"type": "object",
"required": [
"name",
"role"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"role": {
"enum": [
"primary",
"competitor",
"tracked_only"
],
"type": "string"
},
"description": {
"type": "string"
}
},
"additionalProperties": false
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Attach a handle, hashtag or keyword attribution alias. A handle alias marks that platform account as brand-owned and requires its platform; it does not monitor the account; no collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| alias* | object | |
| brandId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"brandId",
"alias"
],
"properties": {
"alias": {
"type": "object",
"required": [
"alias_type",
"alias"
],
"properties": {
"alias": {
"type": "string",
"minLength": 1
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube",
"douyin",
"xhs"
],
"type": "string",
"description": "Required for a handle: the platform the account is on."
},
"alias_type": {
"enum": [
"handle",
"hashtag",
"keyword"
],
"type": "string"
}
},
"additionalProperties": false
},
"brandId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Create a named brand comparison set; no tracking or collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| group* | object | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"group"
],
"properties": {
"group": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string"
}
},
"additionalProperties": false
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Save the specified keyword and associations; does not create monitoring or collect provider data. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| keyword* | object | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"keyword"
],
"properties": {
"keyword": {
"type": "object",
"required": [
"term"
],
"properties": {
"term": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"active": {
"type": "boolean"
},
"locale": {
"type": "string",
"maxLength": 24
},
"region": {
"type": "string",
"maxLength": 16
},
"source": {
"type": "string",
"maxLength": 80
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"sources": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"minLength": 1
},
"maxItems": 20
},
"language": {
"type": "string",
"maxLength": 16
},
"intentIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"localeKey": {
"type": "string",
"maxLength": 24
},
"pillarIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"productId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"personaIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"provenance": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"opportunityKey": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Save the specified keyword batch; does not create monitoring or collect provider data. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| keywords* | array | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"keywords"
],
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "object",
"required": [
"term"
],
"properties": {
"term": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"active": {
"type": "boolean"
},
"locale": {
"type": "string",
"maxLength": 24
},
"region": {
"type": "string",
"maxLength": 16
},
"source": {
"type": "string",
"maxLength": 80
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"sources": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"minLength": 1
},
"maxItems": 20
},
"language": {
"type": "string",
"maxLength": 16
},
"intentIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"localeKey": {
"type": "string",
"maxLength": 24
},
"pillarIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"productId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"personaIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"provenance": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"opportunityKey": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 200,
"minItems": 1
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Save the user's evidence-backed strategy persona; never fabricate private audience demographics. No provider collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| persona* | object | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"persona"
],
"properties": {
"persona": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"active": {
"type": "boolean"
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"languages": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"description": "BCP-47 locale tag, e.g. en-SG or zh-Hans; backend validates tags."
},
"maxItems": 50
},
"description": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 4000
},
{
"type": "null"
}
]
},
"originRegions": {
"type": "array",
"items": {
"type": "string",
"maxLength": 16,
"minLength": 1
},
"maxItems": 50
}
},
"additionalProperties": false
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Create the requested single-platform tracking group; does not establish populated or fresh evidence. A group with the same name (trimmed, case-insensitive), platform and locale_key is returned instead of a duplicate, with reused_existing=true. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| name* | string | |
| brand_id | string | |
| platform | string | |
| locale_key | string | Optional language-market key such as en-SG; part of the group identity. |
| description | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| next_refresh_at | string | |
| refresh_frequency | string |
Save a requested fact, preference, decision or constraint. No provider collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| note* | object | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"note"
],
"properties": {
"note": {
"type": "object",
"required": [
"type",
"bodyMd"
],
"properties": {
"key": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"tags": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"type": {
"enum": [
"fact",
"preference",
"decision",
"constraint",
"workflow",
"task"
],
"type": "string"
},
"title": {
"type": "string",
"maxLength": 200
},
"bodyMd": {
"type": "string",
"maxLength": 50000,
"minLength": 1
},
"confidence": {
"type": "number",
"maximum": 1,
"minimum": 0
},
"importance": {
"type": "number",
"maximum": 1,
"minimum": 0
},
"provenance": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"pinnedToCore": {
"type": "boolean"
},
"lastConfirmedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Delete the requested comparison set; no provider collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| groupId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"groupId"
],
"properties": {
"groupId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Delete only the requested keyword record. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| keywordId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"keywordId"
],
"properties": {
"keywordId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Delete the explicitly requested group; does not silently replace it or recollect evidence. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| group_id* | integer | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"group_id"
],
"properties": {
"group_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Delete the requested tracking item. This changes ongoing monitoring; it is not needed for account metrics. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| item_id* | integer | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"item_id"
],
"properties": {
"item_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Read diagnostics for the existing journey scope without starting another run. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| filters | object | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| diagnosticLimit | integer | |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"filters": {
"type": "object",
"properties": {
"region": {
"type": "string",
"maxLength": 16,
"minLength": 1
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"platformKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"includeWorkspaceNeutral": {
"type": "boolean"
}
},
"additionalProperties": false
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"diagnosticLimit": {
"type": "integer",
"maximum": 1000,
"exclusiveMinimum": 0
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}Look up released capability metadata. Optional reference; this does not gate execution or authorize work.
| Argument | Type | Description |
|---|---|---|
| operationId | string | Deprecated operation identifier; returns its exact canonical replacement when recorded. |
| capabilityId | string | When set, returns one capability instead of the full registry. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"operationId": {
"type": "string",
"description": "Deprecated operation identifier; returns its exact canonical replacement when recorded."
},
"capabilityId": {
"type": "string",
"description": "When set, returns one capability instead of the full registry."
}
},
"additionalProperties": false
}Discover the canonical SocialSeal concept registry: metric concepts (discoverability, visibility, share of voice, reach, ranking, sentiment) and the domain glossary, with definitions, distinctions, required dimensions, evidence requirements, and input-only aliases.
| Argument | Type | Description |
|---|---|---|
| conceptId | string | When set, returns one concept instead of the full registry. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"conceptId": {
"type": "string",
"description": "When set, returns one concept instead of the full registry."
}
},
"additionalProperties": false
}Commit Topics, assignments and search activations atomically for a previewed plan. Requires planFingerprint and idempotencyKey. Duplicate retries return the original created or reused result. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| type | string | |
| items | array | Batch searches. Each item may include value, region, platform, and topicRefs. |
| value | string | |
| region | string | |
| command | object | Canonical preview command snapshot. Send this on execute so automatic assignments are not reclassified. |
| brandIds | array | |
| platform* | string | Supported tracking platform key, such as instagram, tiktok or youtube; the backend rejects unsupported platforms. |
| topicMode | string |
Track the selected Explore searches in Monitor under one Topic on the chosen platforms and cadence, using the planFingerprint from the activation preview. Reuses matching tracked searches and moves them to the chosen cadence; a paused one must be reviewed first. Setup is free; the first scheduled refresh starts on the next scheduler pass and each refresh is charged when it collects. Returns status, Topic and tracking item ids; collected results are available later. Requires an explicit workspace and idempotencyKey; supply confirmedScopeFingerprint only after the preview required confirmation (an unusually large scope, or a scheduled search moving to another cadence).
| Argument | Type | Description |
|---|---|---|
| body | object | Optional complete canonical activateSearches body; explicit fields override it. |
| cadence | string | Refresh cadence; defaults to weekly. Each refresh is charged when it collects. |
| handoffId | string | |
| topicName | string | Topic the selected searches are tracked under; an existing Topic with this name is reused. |
| selectionId | string | |
| workspaceId | string | |
| actorContext | object | |
| idempotencyKey |
Apply one canonical interpretation correction with stable retry identity and the exact labels and memberships supplied by the caller.
| Argument | Type | Description |
|---|---|---|
| body | object | Optional complete canonical applyInterpretationCorrection body; explicit fields override it. |
| labels | array | |
| status | string | |
| lineageId | string | |
| operation | string | |
| snapshotId | string | |
| memberships | array | |
| workspaceId | string | |
| actorContext | object | |
| changeSummary | string | null | |
Create a shareable JSON report from an existing Explore selection, including its saved search terms, interpretation, evidence and limitations. Saves an immutable report and creates an external share link valid for 30 days. Requires an explicit workspace, selection and idempotencyKey. Retries reuse the report but issue a fresh share link.
| Argument | Type | Description |
|---|---|---|
| body | object | Optional complete canonical createDeliverable body; explicit fields override it. |
| handoffId | string | |
| selectionId | string | |
| workspaceId | string | |
| actorContext | object | |
| idempotencyKey | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"description": "Optional complete canonical createDeliverable body; explicit fields override it.",
"additionalProperties": {}
},
"handoffId": {
"type": "string",
"format": "uuid"
},
"selectionId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"actorContext": {
"type": "object",
"additionalProperties": {}
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
}
},
"additionalProperties": false
}Read one canonical Explore lineage, snapshot, run, selection, or compatible snapshot comparison. The response is returned without collapsing evidence, unavailable sources, or partial states. A snapshot's signalRanking orders its terms by observed demand components (Google volume, autocomplete salience, search-result response and engagement); a null calibrated index or insufficient_evidence state means the composite was gated, not that demand is unknown, so prioritise with signalRanking and its evidenceLevel.
| Argument | Type | Description |
|---|---|---|
| body | object | Optional canonical read body; explicit fields override it. |
| page | integer | |
| sort | string | |
| runId | string | |
| outcome | string | |
| pageSize | integer | |
| resource | string | |
| lineageId | string | |
| snapshotId | string |
Prepare a server-issued Explore continuation for the selected destination. A handoff is not action acceptance and carries no client-inferred payload.
| Argument | Type | Description |
|---|---|---|
| body | object | Optional complete canonical prepareHandoff body; explicit fields override it. |
| destination | string | |
| selectionId | string | |
| workspaceId | string | |
| actorContext | object | |
| idempotencyKey | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"description": "Optional complete canonical prepareHandoff body; explicit fields override it.",
"additionalProperties": {}
},
"destination": {
"enum": [
"home",
"monitor",
"study",
"create",
"find_creators",
"seal",
"deliverable_share"
],
"type": "string"
},
"selectionId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"actorContext": {
"type": "object",
"additionalProperties": {}
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
}
},
"additionalProperties": false
}Read the canonical workspace Explore overview, including lineages, latest snapshots, recommendations, capabilities, and blocking reasons. Each snapshot carries signalRanking: its terms ordered by observed demand signals with an evidenceLevel (strong/indicative/untested), usable for prioritising even when the calibrated index is null. The default summary view omits evidence bodies; read a snapshot with socialseal_explore_get for full components and evidence.
| Argument | Type | Description |
|---|---|---|
| body | object | Optional canonical workspaceOverview fields. |
| page | integer | |
| sort | string | |
| view | string | summary (default) omits snapshot diagnostics and evidence manifests; read one snapshot with socialseal_explore_get for full evidence. |
| limit | integer | |
| outcome | string | |
| pageSize | integer | |
| workspaceId | string | Optional workspace UUID. Reads resolve the live configured workspace when omitted. |
Preview tracking an immutable Explore selection's searches under one Topic on the chosen platforms and cadence, without tracking anything. Returns the server plan, its planFingerprint, searches already tracked on another cadence (cadenceChanges) and whether confirmation is required.
| Argument | Type | Description |
|---|---|---|
| body | object | Optional complete canonical activationPreview body; explicit fields override it. |
| cadence | string | Refresh cadence; defaults to weekly. Each refresh is charged when it collects. |
| handoffId | string | |
| topicName | string | Topic the selected searches are tracked under; an existing Topic with this name is reused. |
| selectionId | string | |
| workspaceId | string | |
| actorContext | object | |
| sourcePlatforms | array | Platforms to track the selected searches on, for example ["tiktok"]. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"description": "Optional complete canonical activationPreview body; explicit fields override it.",
"additionalProperties": {}
},
"cadence": {
"enum": [
"daily",
"weekly",
"monthly"
],
"type": "string",
"description": "Refresh cadence; defaults to weekly. Each refresh is charged when it collects."
},
"handoffId": {
"type": "string",
"format": "uuid"
},
"topicName": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Topic the selected searches are tracked under; an existing Topic with this name is reused."
},
"selectionId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"actorContext": {
"type": "object",
"additionalProperties": {}
},
"sourcePlatforms": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Platforms to track the selected searches on, for example [\"tiktok\"]."
}
},
"additionalProperties": false
}Read the server-owned acquisition plan for an authorized workspace, anchor, market and language. Returns planFingerprint, estimated credits, capacity, source availability, blocking reasons and confirmationRequired. Does not create a lineage, queue a run or collect provider evidence. Pass the returned planFingerprint as previewFingerprint to socialseal_explore_start with the same scope. Ordinary plans need no additional user confirmation; request scope confirmation only when confirmationRequired is true.
| Argument | Type | Description |
|---|---|---|
| anchor* | object | |
| marketCode* | string | |
| languageTag* | string | |
| workspaceId* | string | |
| actorContext | object | |
| providerBasket | array |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"anchor",
"marketCode",
"languageTag"
],
"properties": {
"anchor": {
"type": "object",
"anyOf": [
{
"type": "object",
"required": [
"anchorKind",
"subjectId"
],
"properties": {
"subjectId": {
"type": "string",
"format": "uuid"
},
"anchorKind": {
"type": "string",
"const": "search_term"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"anchorKind",
"brandId"
],
"properties": {
"brandId": {
"type": "string",
"format": "uuid"
},
"anchorKind": {
"type": "string",
"const": "brand"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"anchorKind",
"brandId",
"offeringRef",
"offeringRevisionId"
],
"properties": {
"brandId": {
"type": "string",
"format": "uuid"
},
"anchorKind": {
"type": "string",
"const": "offering"
},
"offeringRef": {
"type": "string",
"minLength": 1
},
"offeringRevisionId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"anchorKind",
"audienceNeedRef"
],
"properties": {
"anchorKind": {
"type": "string",
"const": "audience_need"
},
"audienceNeedRef": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"anchorKind",
"audienceNeedRef"
],
"properties": {
"anchorKind": {
"type": "string",
"const": "audience_problem"
},
"audienceNeedRef": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"anchorKind",
"competitorBrandId"
],
"properties": {
"anchorKind": {
"type": "string",
"const": "competitor"
},
"competitorBrandId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"anchorKind",
"topicId"
],
"properties": {
"topicId": {
"type": "string",
"format": "uuid"
},
"anchorKind": {
"type": "string",
"const": "workspace_topic"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"anchorKind",
"topicIds"
],
"properties": {
"topicIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1
},
"anchorKind": {
"type": "string",
"const": "workspace_topics"
}
},
"additionalProperties": false
}
]
},
"marketCode": {
"type": "string",
"minLength": 1
},
"languageTag": {
"type": "string",
"minLength": 1
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"actorContext": {
"type": "object",
"additionalProperties": {}
},
"providerBasket": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"additionalProperties": false
}Queue a new demand-research run for an existing Explore lineage. May collect new provider evidence and consume credits. Requires the workspace, lineage and retry key. Returns run identifiers and execution state. Reuse the same idempotencyKey; supply confirmedScopeFingerprint only after the preview required confirmation (an unusually large scope, or a scheduled search moving to another cadence).
| Argument | Type | Description |
|---|---|---|
| body | object | Optional complete canonical refreshLineage body; explicit fields override it. |
| lineageId | string | |
| quoteOnly | boolean | |
| maxCostUsd | string | |
| workspaceId | string | |
| actorContext | object | |
| evidenceWindow | object | |
| idempotencyKey | string | |
| providerBasket | array | |
| confirmedScopeFingerprint |
Persist an exact, user-confirmed Explore selection for a stated destination and intended use. No additional terms are inferred or added.
| Argument | Type | Description |
|---|---|---|
| body | object | Optional complete canonical createSelection body; explicit fields override it. |
| items | array | |
| lineageId | string | |
| snapshotId | string | |
| intendedUse | string | |
| workspaceId | string | |
| actorContext | object | |
| userQuestion | string | null | |
| idempotencyKey | string | |
| intendedDestination | string | |
| continuationMetadata | object |
Start audience-demand research for the supplied anchor, market and language. Creates a research lineage and queues a collection run, which may consume credits and provider costs. First call socialseal_explore_preview_start; use its planFingerprint as previewFingerprint with the same scope, explicit workspace and retry key. Returns lineage/run identifiers and execution state; inspect the run for results. If the server requests scope confirmation, supply confirmedScopeFingerprint only after the user confirms that scope, reusing the same idempotencyKey.
| Argument | Type | Description |
|---|---|---|
| body | object | Optional complete canonical startLineage body; explicit fields override it. |
| anchor | object | |
| quoteOnly | boolean | |
| sourceRef | string | null | |
| marketCode | string | |
| maxCostUsd | string | |
| sourceKind | string | |
| languageTag | string | |
| workspaceId | string | |
Export the requested brief version for handoff. No new provider collection; preserve returned artifact and evidence links. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| version | integer | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| opportunityKey* | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"opportunityKey"
],
"properties": {
"version": {
"type": "integer",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"opportunityKey": {
"type": "string",
"maxLength": 128,
"minLength": 8
}
},
"additionalProperties": false
}Export a SocialSeal report. Use reportType search_results_enriched, format csv and payload.groupIds for ranked search results; reuse the workspace from the group lookup. Poll the returned export ID while pending, then fetch download_url or page socialseal_read_export_chunk with read_token until has_more is false. Report partial coverage if retrieval stops early. Search rows describe videos surfaced for selected queries at capture time, not search volume or total market demand. Within one platform, market and capture window, result counts, rank and views remain valid relative demand signals for comparing queries; when asked to prioritise, rank with them and label confidence instead of declining. Region is the collection market, not verified viewer geography. Views/likes/saves are video engagement snapshots, not engagement attributable to that query or gains during the export window. State query/platform/market/date scope and coverage; deduplicate videos before aggregating across queries. Define rate denominators and preserve missing values as unknown. Inspect relevant video evidence before recommending a creative treatment.
| Argument | Type | Description |
|---|---|---|
| body | object | Report export body. Include reportType, format, and payload. |
| format | string | Export format. search_results_enriched supports only "csv". |
| payload | object | Required report payload. For search_results_enriched, include payload.groupIds with numeric tracking group ids. |
| reportType | string | Required report type. Use "search_results_enriched" for ranked discoverability/search results. |
| workspaceId | string |
Export legacy time-window tracking data for the authenticated SocialSeal user. Always reuse the workspaceId from the lookup that returned the selected group or tracking item; numeric IDs are not sufficient workspace context. Fulfilled as an export artifact: returns download_url plus a read_token for in-session paginated reads with socialseal_read_export_chunk when the URL cannot be fetched. For ranked discoverability, use socialseal_export_report with reportType search_results_enriched.
| Argument | Type | Description |
|---|---|---|
| body | object | Legacy export body. Provide group_id or tracking_item_id, plus required time_period such as "30d". |
| groupId | integer | string | Convenience alias for body.group_id, a numeric tracking_group id. |
| group_id | integer | string | Convenience field for body.group_id, a numeric tracking_group id. |
| timePeriod | string | Required legacy export window unless supplied in body.time_period, for example "30d". |
| time_period | string | Required legacy export window unless supplied in body.timePeriod, for example "30d". |
| workspaceId | string | Required explicit workspace from the same lookup that returned the selected group or tracking item (unless body.workspaceId is provided). Workspace defaults are never used for exports. |
| trackingItemId |
If the workspace has no funding, offer the complimentary Visibility Check first (socialseal_start_visibility_check). When this action returns reason funding_required with suggestedTool, it did not run: relay its text, collect what missing lists, and once the user agrees call that tool with suggestedArguments plus brand as locator, market as market and the business's own website as targetWebsiteUrl. Retrieve assets for stored post identifiers. TikTok photo/carousel posts return ordered signed slide images; video posts return video/frame assets. Missing frame extraction or requested analysis may incur processing cost under existing controls. Returns per-item state and source links; poll analysis by returned ID, not URL. Separate observed hooks/shots/transcripts from model interpretations. Photo/carousel analysis uses one-based slideIndex references; it provides no video timing, motion or audio evidence. likelyReasonItRanks and similar explanations are hypotheses, not measured ranking causes or independent proof of effectiveness. Cite the source post and inspect whether its audience, topic and production context transfer to the requested brief. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| items* | array | |
| quoteOnly | boolean | |
| frameCount | integer | |
| maxCostUsd | string | |
| workspaceId* | string |
Finalize the requested upload only after bytes are uploaded and rights are attested. May trigger existing clip-analysis processing; preserve provider/admission failures. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| width | integer | null | |
| clipId* | string | |
| height | integer | null | |
| fileName* | string | |
| mimeType* | string | |
| quoteOnly | boolean | |
| sizeBytes* | integer | |
| maxCostUsd | string | |
| posterPath | string | null | |
| storagePath |
Find a target by exact type, value, platform and region, including inactive matches. Returns found=false when it is not tracked in this workspace. Does not create tracking. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| region | string | |
| platform* | string | |
| track_type* | string | |
| track_value* | string | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"platform",
"track_type",
"track_value"
],
"properties": {
"region": {
"type": "string",
"minLength": 1
},
"platform": {
"type": "string",
"minLength": 1
},
"track_type": {
"type": "string",
"minLength": 1
},
"track_value": {
"type": "string",
"minLength": 1
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}Generate a blueprint for the supplied scope or manual videos. May consume credits; use previewOnly to inspect selection and retain existing admission/readiness controls. Read the returned opportunity/version with socialseal_get_blueprint; only a usable generated blueprint should feed socialseal_generate_brief. Draft means pending evidence and missing_data requires inspecting the stated gap. This is reference synthesis, not measured proof of creative effectiveness or a finished video. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| title | string | |
| listId | string | |
| region | string | |
| topicId | string | |
| language | string | |
| pillarId | string | |
| quoteOnly | boolean | |
| scopeType* | string | |
| videoUids | array |
Create a video, creator, UGC or editor brief with hooks and shot direction. Use an existing blueprintId/version or a topic, competitor or tracking_group scope; retrievalPrompt refines scoped retrieval and cannot accompany blueprintId/version. Carry approved audience/product facts and constraints in brandContext; do not assume project documents are loaded. Read existing work with socialseal_get_brief, edit with socialseal_update_brief, and export with socialseal_export_brief before formatting as Word/PDF. May consume credits under existing controls. Generated status does not establish factual accuracy, executable timing or creative quality; inspect the returned evidence and missing-data states. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| title | string | |
| listId | string | |
| region | string | |
| topicId | string | |
| language | string | |
| pillarId | string | |
| quoteOnly | boolean | |
| scopeType | string |
Free stored evidence read. Page both posts and unresolvedPosts with offset/limit until pagination.hasMore=false. To archive immutable raw provider pages, request each sequence from captureManifest using captureSequence. Preserve null metrics, source IDs, observation times, partial coverage and cost uncertainty. No provider call or new charge.
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| limit | integer | |
| offset | integer | |
| workspaceId* | string | |
| captureSequence | integer | |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"captureSequence": {
"type": "integer",
"exclusiveMinimum": 0
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}Read the requested version and source evidence of a saved blueprint; missing evidence remains explicit. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| version | integer | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| historyLimit | integer | |
| includeHistory | boolean | |
| opportunityKey* | string | |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"opportunityKey"
],
"properties": {
"version": {
"type": "integer",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"historyLimit": {
"type": "integer",
"maximum": 20,
"exclusiveMinimum": 0
},
"includeHistory": {
"type": "boolean"
},
"opportunityKey": {
"type": "string",
"maxLength": 128,
"minLength": 8
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}Read existing shot panels and source references with expiring signed URLs; no new collection. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| blueprintId* | string | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| signedUrlSeconds | integer |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"blueprintId"
],
"properties": {
"blueprintId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"signedUrlSeconds": {
"type": "integer",
"maximum": 7200,
"minimum": 60,
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}Read the published content Strategy for a Brand (default: the Workspace's primary Brand): offer, wanted and unwanted audiences, frictions, messaging and production rules, angle ledger and decision tests, plus any pending draft. Call before content strategy, ideas, briefs, calendars, captions or interpreting demand/performance data, and apply it as described in its guidance. state=missing (no Strategy yet) and state=no_brand (no primary Brand yet) are normal results, not failures: proceed with the user's request on stated assumptions and follow the returned guidance. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| brandId | string | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"brandId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}Read an exact saved briefId, or a version and evidence by opportunityId (or the deprecated opportunityKey). Brand/strategy setup is not required to retrieve it. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| brandId | string | null | |
| briefId | string | |
| version | integer | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| historyLimit | integer | |
| opportunityId | string | Opportunity UUID returned by Monitor, Study or Create. Supply this or opportunityKey. |
| includeHistory | boolean | |
| opportunityKey | string | Deprecated: use opportunityId. Accepted for one catalogue version. |
Read outcomes only for posts actually linked to the specified brief: per post, the Monitor's Share of Voice and Discoverability for the Brief's topic before and after publication (monitor, with method and missingReasons; a post absent from tracked results is not_observed and unknown views stay null), plus legacy weekly search rank as a secondary line. Observational, not causal; this sample is not total account reach. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| region | string | null | |
| briefId | string | null | Exact saved Brief version; omit only for an explicit opportunity-wide read. |
| platforms | array | null | |
| weekStart | string | null | |
| windowWeeks | integer | null | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| opportunityId | string | Opportunity UUID returned by Monitor, Study or Create. Supply this or opportunityKey. |
Check evidence readiness for creative brief generation or editing. This check does not gate unrelated reads, account metrics or URL analysis. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| action | string | |
| brandId | string | null | |
| topicId | string | |
| pillarId | string | null | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| opportunityKey | string | |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"action": {
"enum": [
"create",
"edit"
],
"type": "string"
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"topicId": {
"type": "string",
"format": "uuid"
},
"pillarId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"opportunityKey": {
"type": "string",
"maxLength": 128,
"minLength": 8
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}Read progress, result and failure evidence for an existing brief run. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| runId* | string | |
| brandId | string | null | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"runId"
],
"properties": {
"runId": {
"type": "string",
"format": "uuid"
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}Read core context, building its stored cache from existing notes if absent. No provider collection or model cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Read the status and evidence of one caller/workspace-scoped creator collection receipt. No provider call, charge or new tracker. Running receipts return continuation; complete and failed are terminal. Preserve partial metrics and brand evidence.
| Argument | Type | Description |
|---|---|---|
| id* | string | Collection receipt id returned by the collect action. |
| brandId | string | Optional existing workspace brand for partnership context. Missing brand evidence does not block metrics. |
| workspaceId* | string | |
| recentPostCount | integer | Requested latest account posts, including images, carousels and videos. Coverage may be incomplete. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Collection receipt id returned by the collect action."
},
"brandId": {
"type": "string",
"format": "uuid",
"description": "Optional existing workspace brand for partnership context. Missing brand evidence does not block metrics."
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"recentPostCount": {
"type": "integer",
"default": 5,
"description": "Requested latest account posts, including images, carousels and videos. Coverage may be incomplete.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}Stored Instagram evidence only. To collect any account, Instagram or TikTok, use socialseal_collect_account. Read a supplied Instagram profile URL or handle directly, with account timeline posts (images, carousels and videos), publication dates, captions, available metrics, deterministic average views and engagement rates with formulas/denominators, freshness and coverage, plus accessible workspace brand context for host-owned brand-fit assessment. No resolver, skill or tracked-search setup prerequisite. Stored evidence only: no provider requests, credits, or persistent tracker. A fresh request returns FRESH_COLLECTION_REQUIRED and existing evidence; socialseal_collect_account performs a separate bounded collection. Synchronous response; collection.continuation=null, no polling. Respect coverage.latestClaim; a partial timeline cannot establish the latest account posts. Missing brand evidence does not block metrics. Public views do not establish demographics or unique reach.
| Argument | Type | Description |
|---|---|---|
| target* | string | Named Instagram profile URL or @handle; not a search keyword or post URL. |
| brandId | string | Optional existing workspace brand for partnership context. Missing brand evidence does not block metrics. |
| platform* | string | Stored Instagram evidence only. To collect any account, Instagram or TikTok, use socialseal_collect_account. |
| freshness | string | Stored evidence read. Fresh requests return FRESH_COLLECTION_REQUIRED alongside stored evidence; use the separate bounded collect action. |
Stored Instagram evidence only. To collect any account, Instagram or TikTok, use socialseal_collect_account. Read a supplied Instagram profile URL or handle directly, with account timeline posts (images, carousels and videos), publication dates, captions, available metrics, deterministic average views and engagement rates with formulas/denominators, freshness and coverage, plus accessible workspace brand context for host-owned brand-fit assessment. No resolver, skill or tracked-search setup prerequisite. Stored evidence only: no provider requests, credits, or persistent tracker. A fresh request returns FRESH_COLLECTION_REQUIRED and existing evidence; socialseal_collect_account performs a separate bounded collection. Synchronous response; collection.continuation=null, no polling. Respect coverage.latestClaim; a partial timeline cannot establish the latest account posts. Missing brand evidence does not block metrics. Public views do not establish demographics or unique reach.
| Argument | Type | Description |
|---|---|---|
| target* | string | Named Instagram profile URL or @handle; not a search keyword or post URL. |
| brandId | string | Optional existing workspace brand for partnership context. Missing brand evidence does not block metrics. |
| platform* | string | Stored Instagram evidence only. To collect any account, Instagram or TikTok, use socialseal_collect_account. |
| freshness | string | Stored evidence read. Fresh requests return FRESH_COLLECTION_REQUIRED alongside stored evidence; use the separate bounded collect action. |
Get the current workspace before a workspace-scoped action when the user has not named one. Hosted MCP returns the sole workspace the user can reach, or none when there are several: then ask the user which one. Local MCP returns the workspace selected in environment/configuration.
No arguments.
{
"type": "object",
"properties": {}
}Read stored Google AI, ChatGPT, Gemini and Claude answers and citations, preserving the actual query and historical capture scope; each answer's run names its engine. Filter with engine to compare one engine's answers. Paginate offset/limit. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| query | string | |
| runId | integer | |
| engine | string | Only this engine's answers; every engine's when omitted. |
| offset | integer | |
| skipCache | boolean | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| trackingItemId | integer | |
| includeCitations |
Read a saved operation's status, price, retained result and USD receipt. Polling and retrieving prior results are free. A funding_required operation has not started: after the workspace is topped up, send the same request again with the same idempotency key. Funding alone is not successful task completion.
| Argument | Type | Description |
|---|---|---|
| operationId* | string | Preserved operationId returned by the requested task. Do not supply a replacement task payload. |
| workspaceId* | string | Workspace selected for the original request and its funding. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"operationId"
],
"properties": {
"operationId": {
"type": "string",
"format": "uuid",
"description": "Preserved operationId returned by the requested task. Do not supply a replacement task payload."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Workspace selected for the original request and its funding."
}
},
"additionalProperties": false
}Read a selected existing journey and optionally its latest execution. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| journeyId* | string | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| includeLatestRun | boolean | |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"journeyId"
],
"properties": {
"journeyId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"includeLatestRun": {
"type": "boolean"
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}Read status and available results of the returned journey run; do not restart it to poll. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| runId* | string | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"runId"
],
"properties": {
"runId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}Return download URLs for the full SocialSeal agent-skills repository (zip/tarball) plus the install command, so the agent or user can download every skill at once.
No arguments.
{
"type": "object",
"properties": {}
}Read-only polling for a known SocialSeal async run, export, or group refresh. UUID auto ids are journey runs; numeric auto ids are AI answer runs (Google AI, ChatGPT, Gemini or Claude). Both are workspace-scoped, as are google_ai_run, journey_run, explore_run, and video_analysis. Pass the workspaceId from the lookup that returned the run. MCP-host errors such as "No approval received" occur before SocialSeal executes this tool; never describe them as SocialSeal billing, workspace approval, or job-status errors.
| Argument | Type | Description |
|---|---|---|
| id* | string | number | |
| kind | string | |
| workspaceId | string | Pass the workspace from the lookup that returned this run id. Required for auto/google_ai_run/journey/explore/video polls unless the user can reach only one workspace. |
| resultsLimit | integer | |
| includeResults | boolean |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": [
"string",
"number"
]
},
"kind": {
"enum": [
"auto",
"group_refresh",
"google_ai_run",
"journey_run",
"explore_run",
"video_analysis",
"export"
],
"type": "string",
"default": "auto"
},
"workspaceId": {
"type": "string",
"description": "Pass the workspace from the lookup that returned this run id. Required for auto/google_ai_run/journey/explore/video polls unless the user can reach only one workspace."
},
"resultsLimit": {
"type": "integer",
"exclusiveMinimum": 0
},
"includeResults": {
"type": "boolean"
}
},
"additionalProperties": false
}Read an existing tracking group's configuration by ID. Reads stored data; does not refresh evidence or create tracking. No new collection cost.
| Argument | Type | Description |
|---|---|---|
| group_id* | integer | Tracking group ID returned by a group lookup; retain its workspace context. |
| workspaceId | string | Optional workspace override. Omit only when the user can reach a single workspace. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"group_id"
],
"properties": {
"group_id": {
"type": "integer",
"description": "Tracking group ID returned by a group lookup; retain its workspace context.",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Optional workspace override. Omit only when the user can reach a single workspace."
}
},
"additionalProperties": false
}Compare expected memberships with stored items in the authorized tracking group, including missing/extra items, platform mismatches and optional stored refresh-job status. Omit expected_items to inspect current membership. Reads existing configuration/jobs only; no collection, refresh, mutation or new cost. Completeness does not establish fresh evidence. Reuse the workspace from the group lookup.
| Argument | Type | Description |
|---|---|---|
| group_id* | integer | Tracking group ID returned by a group lookup; retain its workspace context. |
| workspaceId | string | Optional workspace override. Omit only when the user can reach a single workspace. |
| expected_items | array | |
| include_refresh_status | boolean |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"group_id"
],
"properties": {
"group_id": {
"type": "integer",
"description": "Tracking group ID returned by a group lookup; retain its workspace context.",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Optional workspace override. Omit only when the user can reach a single workspace."
},
"expected_items": {
"type": "array",
"items": {
"type": "object",
"anyOf": [
{
"type": "object",
"required": [
"item_id"
],
"properties": {
"item_id": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"track_type",
"track_value"
],
"properties": {
"region": {
"type": "string",
"description": "Optional region constraint; omitted matches any stored region for this tuple."
},
"platform": {
"type": "string",
"minLength": 1,
"description": "Optional platform-name constraint, compared with the joined stored platform name."
},
"track_type": {
"type": "string",
"minLength": 1
},
"platform_id": {
"type": "integer",
"description": "Optional numeric platform constraint.",
"exclusiveMinimum": 0
},
"track_value": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
]
}
},
"include_refresh_status": {
"type": "boolean"
}
},
"additionalProperties": false
}Read the existing group's collection queue state; does not start another refresh. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| group_id* | integer | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"group_id"
],
"properties": {
"group_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}Read the workspace's canonical tracked-item total and breakdown: one item per search in one market on one platform, hashtag or account, counted once however many groups include it, with paused items separate. Use this total whenever you state how many searches, hashtags or accounts are tracked; do not add up group item counts or count a page of list results. Pass includeItems for a page of items, including paused items, with platform, market, frequency, last and next collection, latest refresh outcome and Monitor report inclusion. The summary always covers the whole workspace. To read every item, repeat with offset=pagination.nextOffset while pagination.hasMore is true. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Items per page when includeItems=true; defaults to 20, maximum 100. |
| offset | integer | Zero-based item offset; defaults to 0. Use pagination.nextOffset to continue. |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| includeItems | boolean |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"description": "Items per page when includeItems=true; defaults to 20, maximum 100.",
"exclusiveMinimum": 0
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based item offset; defaults to 0. Use pagination.nextOffset to continue."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"includeItems": {
"type": "boolean"
}
},
"additionalProperties": false
}Read one existing tracked search, hashtag or account. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| item_id* | integer | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"item_id"
],
"properties": {
"item_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}Read stored analysis for returned video identifiers. URLs are not accepted for polling; missing or pending evidence does not trigger provider work. Separate observed hooks/shots/transcripts from model interpretations. Photo/carousel analysis uses one-based slideIndex references; it provides no video timing, motion or audio evidence. likelyReasonItRanks and similar explanations are hypotheses, not measured ranking causes or independent proof of effectiveness. Cite the source post and inspect whether its audience, topic and production context transfer to the requested brief. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| items* | array | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| includeRawAnalysis | boolean | |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"anyOf": [
{
"type": "object",
"required": [
"videoUid"
],
"properties": {
"videoUid": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"platformVideoId"
],
"properties": {
"platformId": {
"type": "integer",
"exclusiveMinimum": 0
},
"platformVideoId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"minLength": 1
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"searchResultId"
],
"properties": {
"searchResultId": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"videoId"
],
"properties": {
"videoId": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"maxItems": 25,
"minItems": 1
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"includeRawAnalysis": {
"type": "boolean"
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}Read status, available results or a typed failure for an existing video search. Pass its canonical jobId and workspaceId. Read-only; no collection or charge. Poll this action instead of starting the search again. Search rows describe videos surfaced for selected queries at capture time, not search volume or total market demand. Within one platform, market and capture window, result counts, rank and views remain valid relative demand signals for comparing queries; when asked to prioritise, rank with them and label confidence instead of declining. Region is the collection market, not verified viewer geography. Views/likes/saves are video engagement snapshots, not engagement attributable to that query or gains during the export window. State query/platform/market/date scope and coverage; deduplicate videos before aggregating across queries. Define rate denominators and preserve missing values as unknown. Inspect relevant video evidence before recommending a creative treatment.
| Argument | Type | Description |
|---|---|---|
| jobId* | string | Canonical jobId returned by socialseal_search_videos. |
| workspaceId* | string | Workspace supplied when starting the search. |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"jobId"
],
"properties": {
"jobId": {
"type": "string",
"format": "uuid",
"description": "Canonical jobId returned by socialseal_search_videos."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Workspace supplied when starting the search."
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}Retrieve progress, candidate themes or the released complete Visibility Check. Read the same operation after reconnecting; polling costs nothing. Return evidence, scope, freshness and limitations honestly. A report awaiting review is not yet released, and a partial report is not a complete outcome.
| Argument | Type | Description |
|---|---|---|
| operationId* | string | Operation returned by the Visibility Check start action. Reuse across polling and reconnects. |
| workspaceId* | string | Resolve the user's authorized workspace; reuse the only workspace without asking for its ID. |
| evidenceLimit | integer | |
| evidenceOffset | integer | |
| storySnapshotId | string | Pin subsequent evidence pages to the result snapshot returned by the first read. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"operationId"
],
"properties": {
"operationId": {
"type": "string",
"format": "uuid",
"description": "Operation returned by the Visibility Check start action. Reuse across polling and reconnects."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Resolve the user's authorized workspace; reuse the only workspace without asking for its ID."
},
"evidenceLimit": {
"type": "integer",
"maximum": 100,
"minimum": 1
},
"evidenceOffset": {
"type": "integer",
"minimum": 0
},
"storySnapshotId": {
"type": "string",
"format": "uuid",
"description": "Pin subsequent evidence pages to the result snapshot returned by the first read."
}
},
"additionalProperties": false
}Read the workspace's prepaid USD balance, the amount available for new actions (the balance minus the prices of admitted actions still running) and this month's spend, plus any one-time starter grant (starterGrantUsd), which only some eligible Free owners receive, and complimentaryVisibilityCheck (whether this user can still start the free Visibility Check). Read it before promising starter usage or that an action fits within the grant. Subscription credits remain their own allowance and are never converted to a cash balance.
| Argument | Type | Description |
|---|---|---|
| workspaceId* | string | Workspace selected for the original request and its funding. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Workspace selected for the original request and its funding."
}
},
"additionalProperties": false
}Read an existing note by its returned ID. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| noteId* | string | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"noteId"
],
"properties": {
"noteId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}Read known attribution aliases for an accessible brand. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| brandId* | string | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"brandId"
],
"properties": {
"brandId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}Read named sets of existing brands. These are not tracking groups. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}Retrieve existing brand context before asking the user for brand identifiers. Returns canonical brands and workspace roles. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}Read Google AI, ChatGPT, Gemini and Claude run status and progress, scoped to the requested run or tracking item. Each run names its engine. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| runId | integer | |
| offset | integer | |
| skipCache | boolean | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| trackingItemId | integer |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"exclusiveMinimum": 0
},
"runId": {
"type": "integer",
"exclusiveMinimum": 0
},
"offset": {
"type": "integer",
"minimum": 0
},
"skipCache": {
"type": "boolean"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"trackingItemId": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}Read existing keyword records and their evidence/strategy associations. Each keyword carries demandSignals: evidenceLevel (strong/indicative/untested), the demand signals present, and googleSearchVolume.state (not_collected means never fetched, not zero). Listing keywords does not start searches. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| filters | object | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"filters": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"maximum": 10000,
"exclusiveMinimum": 0
},
"limit": {
"type": "integer",
"maximum": 1000,
"exclusiveMinimum": 0
},
"query": {
"type": "string",
"maxLength": 200
},
"active": {
"type": "boolean"
},
"region": {
"type": "string",
"maxLength": 16
},
"sortBy": {
"enum": [
"updatedAt",
"keyword",
"translation",
"region",
"volume",
"competition",
"relevance",
"stage",
"status"
],
"type": "string"
},
"brandId": {
"type": "string",
"format": "uuid"
},
"intentId": {
"type": "string",
"format": "uuid"
},
"language": {
"type": "string",
"maxLength": 16
},
"pageSize": {
"type": "integer",
"maximum": 500,
"exclusiveMinimum": 0
},
"pillarId": {
"type": "string",
"format": "uuid"
},
"intentIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 20
},
"localeKey": {
"type": "string",
"maxLength": 24
},
"personaId": {
"type": "string",
"format": "uuid"
},
"pillarIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 20
},
"productId": {
"type": "string",
"format": "uuid"
},
"ungrouped": {
"type": "boolean"
},
"personaIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 20
},
"sortDirection": {
"enum": [
"asc",
"desc"
],
"type": "string"
},
"opportunityKey": {
"type": "string",
"maxLength": 200
},
"minRelevanceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"relevanceIntentId": {
"type": "string",
"format": "uuid"
},
"relevanceIntentIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 20
},
"relevancePersonaId": {
"type": "string",
"format": "uuid"
},
"relevancePersonaIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 20
},
"includeWorkspaceNeutralFallback": {
"type": "boolean"
}
},
"additionalProperties": false
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}Read saved workspace personas. Personas are supplied strategy records, not inferred private audience demographics. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
}
},
"additionalProperties": false
}List existing journey identities and optionally their latest runs. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| page | integer | |
| filters | object | |
| pageSize | integer | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| includeLatestRun | boolean |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"page": {
"type": "integer",
"exclusiveMinimum": 0
},
"filters": {
"type": "object",
"properties": {
"region": {
"type": "string",
"maxLength": 16,
"minLength": 1
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"platformKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"includeWorkspaceNeutral": {
"type": "boolean"
}
},
"additionalProperties": false
},
"pageSize": {
"type": "integer",
"maximum": 250,
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"includeLatestRun": {
"type": "boolean"
}
},
"additionalProperties": false
}Discover optional task-specific SocialSeal guidance after identifying the requested work. For a content calendar or posting schedule, select socialseal-social-plan-builder; for video/editor/UGC briefs, select socialseal-creator-briefing. Loading guidance does not execute generation tools. Skills are not prerequisites for basic operations. Returns each skill's name and frontmatter description (so you can route without reading every SKILL.md), file paths, shared references, the install command, and the archive download info.
No arguments.
{
"type": "object",
"properties": {}
}Read existing source clips, rights metadata and available clip analysis; expiring media URLs are not permanent assets. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| videoClipIds | array |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"videoClipIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 24
}
},
"additionalProperties": false
}Read the monitored items in an existing tracking group, paginated by page and limit. Stored membership is not fresh search evidence. No collection or new collection cost; no setup prerequisite.
| Argument | Type | Description |
|---|---|---|
| page | integer | |
| limit | integer | |
| group_id* | integer | Tracking group ID returned by a group lookup; retain its workspace context. |
| workspaceId | string | Optional workspace override. Omit only when the user can reach a single workspace. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"group_id"
],
"properties": {
"page": {
"type": "integer",
"exclusiveMinimum": 0
},
"limit": {
"type": "integer",
"exclusiveMinimum": 0
},
"group_id": {
"type": "integer",
"description": "Tracking group ID returned by a group lookup; retain its workspace context.",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Optional workspace override. Omit only when the user can reach a single workspace."
}
},
"additionalProperties": false
}Show existing authorized tracking groups across their configured platforms. Reads stored configuration without collection, refresh or setup; no new collection cost. Use the returned group ID and workspace for subsequent reads. Groups overlap, so never add up items_count for a tracked total; use socialseal_get_tracking_inventory.
| Argument | Type | Description |
|---|---|---|
| workspaceId | string | Optional workspace override. Omit only when the user can reach a single workspace. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Optional workspace override. Omit only when the user can reach a single workspace."
}
},
"additionalProperties": false
}Read existing tracked items and their actual platform/market scope. Results are paged; for how many items are tracked, use socialseal_get_tracking_inventory. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| page | integer | |
| limit | integer | |
| platform | string | |
| is_active | boolean | |
| track_type | string | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| includeInactive | boolean |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"page": {
"type": "integer",
"exclusiveMinimum": 0
},
"limit": {
"type": "integer",
"exclusiveMinimum": 0
},
"platform": {
"type": "string",
"minLength": 1
},
"is_active": {
"type": "boolean"
},
"track_type": {
"type": "string",
"minLength": 1
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"includeInactive": {
"type": "boolean"
}
},
"additionalProperties": false
}Read active Topics with stable IDs, names and descriptions before assigning searches. No collection cost. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}List workspaces visible to the authenticated SocialSeal user. List order and owner role do not identify the default; use defaultWorkspaceId/isDefaultWorkspace, or call socialseal_get_current_workspace before a write when the user did not name a workspace.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| cursor | string | |
| includeInactive | boolean | Deprecated no-op. All owned workspaces are returned regardless of active state. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 500,
"exclusiveMinimum": 0
},
"cursor": {
"type": "string"
},
"includeInactive": {
"type": "boolean",
"description": "Deprecated no-op. All owned workspaces are returned regardless of active state."
}
},
"additionalProperties": false
}Merge the requested source groups into the target group: the target keeps the union of their items (a shared item is still collected once) and the source groups are deleted. All groups must use the target's platform; a source group still referenced elsewhere blocks the whole merge without changes. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| target_group_id* | integer | |
| source_group_ids* | array |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"target_group_id",
"source_group_ids"
],
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"target_group_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"source_group_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"minItems": 1
}
},
"additionalProperties": false
}Change whether the specified note is included in core context. No provider collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| noteId* | string | |
| pinned* | boolean | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"noteId",
"pinned"
],
"properties": {
"noteId": {
"type": "string",
"format": "uuid"
},
"pinned": {
"type": "boolean"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Create the requested source clip upload and return signed upload fields. Requires a separate byte upload and finalize action; no assembled-video output. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| fileName* | string | |
| mimeType* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"fileName",
"mimeType"
],
"properties": {
"fileName": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"mimeType": {
"enum": [
"video/mp4",
"video/quicktime",
"video/webm"
],
"type": "string"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Return the exact Topics to create or reuse, per-search assignments, conflicts, credits and planFingerprint without activating. Use execute_search_activation with that fingerprint to commit. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| type | string | |
| items | array | Batch searches. Each item may include value, region, platform, and topicRefs. |
| value | string | |
| region | string | |
| command | object | Canonical preview command snapshot. Send this on execute so automatic assignments are not reclassified. |
| brandIds | array | |
| platform* | string | Supported tracking platform key, such as instagram, tiktok or youtube; the backend rejects unsupported platforms. |
| topicMode | string |
Save a draft Strategy revision for user review. Pass the complete Strategy and expectedBaseRevisionId (the published revision you read, or null when none exists). Drafts do not affect agents or generation until published. Use it when the user asks to create or change the Strategy, or after they confirm a correction that should persist. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| brandId | string | |
| strategy* | object | Complete replacement Strategy. Distil to decisions that change outputs; the rendered context must stay under 8,000 characters. |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| changeSummary* | string | What changed and why, in one or two sentences. |
| expectedBaseRevisionId* | string | null |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"strategy",
"expectedBaseRevisionId",
"changeSummary"
],
"properties": {
"brandId": {
"type": "string",
"format": "uuid"
},
"strategy": {
"type": "object",
"required": [
"decisionTests"
],
"properties": {
"offer": {
"type": "array",
"items": {
"type": [
"string",
"object"
],
"anyOf": [
{
"type": "string",
"maxLength": 600,
"minLength": 1
},
{
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 600,
"minLength": 1
},
"source": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Where this came from, e.g. client call, lead threads, booking data."
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
}
},
"additionalProperties": false
}
]
},
"maxItems": 12,
"description": "What the brand sells, how it earns, and what counts as a good lead or win."
},
"angles": {
"type": "array",
"items": {
"type": "object",
"required": [
"angle",
"status"
],
"properties": {
"angle": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"reason": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"status": {
"enum": [
"live",
"published",
"rejected",
"paused"
],
"type": "string"
},
"decidedOn": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
},
"additionalProperties": false
},
"maxItems": 60,
"description": "Angle ledger. Supersede entries instead of appending contradictions."
},
"summary": {
"type": "string",
"maxLength": 1200,
"minLength": 1,
"description": "One short positioning paragraph."
},
"frictions": {
"type": "array",
"items": {
"type": [
"string",
"object"
],
"anyOf": [
{
"type": "string",
"maxLength": 600,
"minLength": 1
},
{
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 600,
"minLength": 1
},
"source": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Where this came from, e.g. client call, lead threads, booking data."
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
}
},
"additionalProperties": false
}
]
},
"maxItems": 12,
"description": "Problems the brand removes that make the target buy."
},
"messaging": {
"type": "object",
"properties": {
"use": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 40
},
"avoid": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 40
},
"rules": {
"type": "array",
"items": {
"type": [
"string",
"object"
],
"anyOf": [
{
"type": "string",
"maxLength": 600,
"minLength": 1
},
{
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 600,
"minLength": 1
},
"source": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Where this came from, e.g. client call, lead threads, booking data."
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
}
},
"additionalProperties": false
}
]
},
"maxItems": 12
}
},
"additionalProperties": false
},
"production": {
"type": "array",
"items": {
"type": [
"string",
"object"
],
"anyOf": [
{
"type": "string",
"maxLength": 600,
"minLength": 1
},
{
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 600,
"minLength": 1
},
"source": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Where this came from, e.g. client call, lead threads, booking data."
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
}
},
"additionalProperties": false
}
]
},
"maxItems": 12,
"description": "Real production limits: people, time, footage, duration, branding."
},
"decisionTests": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"maxItems": 8,
"minItems": 1,
"description": "Short yes/no tests every idea, including the user's own, must pass."
},
"targetAudiences": {
"type": "array",
"items": {
"type": [
"string",
"object"
],
"anyOf": [
{
"type": "string",
"maxLength": 600,
"minLength": 1
},
{
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 600,
"minLength": 1
},
"source": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Where this came from, e.g. client call, lead threads, booking data."
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
}
},
"additionalProperties": false
}
]
},
"maxItems": 12,
"description": "Who the content should attract."
},
"excludedAudiences": {
"type": "array",
"items": {
"type": [
"string",
"object"
],
"anyOf": [
{
"type": "string",
"maxLength": 600,
"minLength": 1
},
{
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 600,
"minLength": 1
},
"source": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Where this came from, e.g. client call, lead threads, booking data."
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
}
},
"additionalProperties": false
}
]
},
"maxItems": 12,
"description": "Who the content must not attract (anti-personas), even if they dominate demand."
}
},
"description": "Complete replacement Strategy. Distil to decisions that change outputs; the rendered context must stay under 8,000 characters.",
"additionalProperties": false
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"changeSummary": {
"type": "string",
"maxLength": 1000,
"minLength": 1,
"description": "What changed and why, in one or two sentences."
},
"expectedBaseRevisionId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}Publish a draft Strategy revision so agents and brief generation apply it. Call only after the user has explicitly approved this exact draft in the conversation. Fails with BRAND_STRATEGY_STALE_BASE when the published Strategy changed after the draft was proposed. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| brandId | string | |
| revisionId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"revisionId"
],
"properties": {
"brandId": {
"type": "string",
"format": "uuid"
},
"revisionId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Reactivate the requested existing strategy persona; no provider collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| personaId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"personaId"
],
"properties": {
"personaId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Read rows of a previously generated SocialSeal export artifact in-session, paginated as JSON. Use this when the export tool returns a download_url you cannot fetch (e.g. sandbox egress limits or web_fetch cannot render a CSV attachment). Pass the short download token (the `t` query param from download_url) plus offset and limit. Each call returns { export_history_id, headers, rows, offset, limit, next_offset, total, has_more }. Rows are packed by serialized char budget (not a fixed row count), so `limit` reflects the actual number of rows returned and may be smaller than requested. To page: if has_more is true, call again with offset = next_offset. Repeat until has_more is false. Prefer limit=200 as the max-rows cap. The data stays inside the MCP tool channel, so no URL fetch is required.
| Argument | Type | Description |
|---|---|---|
| t* | string | Short opaque download token from the export result download_url (the `t` query param value). |
| limit | integer | Max rows to return per call. Defaults to 200. |
| offset | integer | Row offset to start reading from. Defaults to 0. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"t"
],
"properties": {
"t": {
"type": "string",
"minLength": 1,
"description": "Short opaque download token from the export result download_url (the `t` query param value)."
},
"limit": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "Max rows to return per call. Defaults to 200."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Row offset to start reading from. Defaults to 0."
}
},
"additionalProperties": false
}Read the full instructions for one SocialSeal skill. Provide skill (and optional file, defaulting to SKILL.md) to read within skills/<skill>/, or provide path to read a repo-relative file under skills/, references/, docs/, templates/, or examples/.
| Argument | Type | Description |
|---|---|---|
| file | string | |
| path | string | |
| skill | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"file": {
"type": "string",
"minLength": 1
},
"path": {
"type": "string",
"minLength": 1
},
"skill": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}Rebuild the core context from existing notes; does not collect social content. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| forceRebuild | boolean |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"forceRebuild": {
"type": "boolean"
}
},
"additionalProperties": false
}Regenerate reference panels for the selected blueprint. May incur processing cost under existing controls; this does not assemble a video. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| quoteOnly | boolean | |
| maxCostUsd | string | |
| blueprintId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| idempotencyKey | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"blueprintId"
],
"properties": {
"quoteOnly": {
"type": "boolean"
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$"
},
"blueprintId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
}
},
"additionalProperties": false
}Queue collection for the existing group. May incur collection cost. Returns the existing refresh polling contract; no completion or freshness claim before status/evidence confirms it. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| force | boolean | |
| group_id* | integer | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"group_id"
],
"properties": {
"force": {
"type": "boolean"
},
"group_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Request fresh collection for an already monitored item. May incur collection cost; retain the returned job/status information and do not duplicate starts. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| endAt | string | |
| item_id* | integer | |
| startAt | string | |
| quoteOnly | boolean | |
| maxCostUsd | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| idempotencyKey | string | |
| recentPostCount | integer | |
| maxProviderRequests | integer |
Remove membership in the requested set; no provider collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| brandId* | string | |
| groupId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"groupId",
"brandId"
],
"properties": {
"brandId": {
"type": "string",
"format": "uuid"
},
"groupId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Remove only the requested group membership. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| item_id* | integer | |
| group_id* | integer | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"group_id",
"item_id"
],
"properties": {
"item_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"group_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Resume collection for a paused item. The result's collection field says what will collect it: monitor, prepaid or subscription (collected from the next scheduled run; prepaid runs are paid from Workspace funds and wait when funds are short), or manual (only on request). Items whose platform cannot collect in their region (TikTok in CN or HK) stay paused and return UNSUPPORTED_PLATFORM_REGION; report that reason rather than retrying. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| item_id* | integer | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"item_id"
],
"properties": {
"item_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Mark the requested strategy persona inactive; no provider collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| personaId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"personaId"
],
"properties": {
"personaId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Retry the existing run under backend context-fingerprint and idempotency checks. May consume credits. Poll socialseal_get_brief_run; do not silently force a full rerun. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| runId* | string | |
| brandId | string | null | |
| quoteOnly | boolean | |
| forceRerun | boolean | |
| maxCostUsd | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| forceFullRerun | boolean | |
| idempotencyKey | string | |
| contextFingerprint | string | null |
Save supplied evidence-backed blueprint content without provider collection. Do not fabricate evidence citations. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| title | string | |
| source | object | Domain metadata, not additional operation arguments. |
| status | string | |
| summary* | string | |
| evidence | array | |
| metadata | object | Domain metadata, not additional operation arguments. |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| bestPractices | array | |
| opportunityKey* | string |
Save supplied brief content tied to a real blueprint version; no provider collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| title | string | |
| status | string | |
| content | object | Domain metadata, not additional operation arguments. |
| summary | string | |
| metadata | object | Domain metadata, not additional operation arguments. |
| rationale | object | Domain metadata, not additional operation arguments. |
| blueprintId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| opportunityKey* | string | |
If the workspace has no funding, offer the complimentary Visibility Check first (socialseal_start_visibility_check). When this action returns reason funding_required with suggestedTool, it did not run: relay its text, collect what missing lists, and once the user agrees call that tool with suggestedArguments plus brand as locator, market as market and the business's own website as targetWebsiteUrl. Start a bounded video search for a query, platform and region. Subscription workspaces pay credits; prepaid workspaces pay the returned USD price only when the search completes with results. Returns jobId when admitted, or a saved operationId with status funding_required when the balance is short: when that result carries suggestedTool, relay its text and offer the free check; otherwise, after a top-up, send the same request again with the same idempotency key; never replace the pending request. Poll socialseal_get_video_search for admitted legacy jobs. Concurrent equivalent searches coalesce. No ongoing tracker is created. Preserve returned coverage and provider limitations. Search rows describe videos surfaced for selected queries at capture time, not search volume or total market demand. Within one platform, market and capture window, result counts, rank and views remain valid relative demand signals for comparing queries; when asked to prioritise, rank with them and label confidence instead of declining. Region is the collection market, not verified viewer geography. Views/likes/saves are video engagement snapshots, not engagement attributable to that query or gains during the export window. State query/platform/market/date scope and coverage; deduplicate videos before aggregating across queries. Define rate denominators and preserve missing values as unknown. Inspect relevant video evidence before recommending a creative treatment.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Fresh-result limit: TikTok 20, Instagram 30, YouTube/Douyin/XHS 50. Default 20. The price uses this requested scope. |
| query* | string |
Find existing brand facts, constraints and decisions in authorized workspace notes. Reads stored evidence/configuration; no provider collection or collection charge. Preserve returned timestamps, coverage, missing evidence and errors. Synchronous; no polling unless the result explicitly supplies continuation.
| Argument | Type | Description |
|---|---|---|
| tags | object | Domain metadata, not additional operation arguments. |
| limit | integer | |
| query | string | |
| types | array | |
| workspaceId | string | Reuse the authorized default or sole accessible workspace when omitted. |
| includeSuperseded | boolean |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"tags": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"limit": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"query": {
"type": "string",
"maxLength": 500
},
"types": {
"type": "array",
"items": {
"enum": [
"fact",
"preference",
"decision",
"constraint",
"workflow",
"task"
],
"type": "string"
}
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"includeSuperseded": {
"type": "boolean"
}
},
"additionalProperties": false
}Change the active state of one attribution alias; no collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| alias* | object | |
| aliasId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"aliasId",
"alias"
],
"properties": {
"alias": {
"type": "object",
"required": [
"is_active"
],
"properties": {
"is_active": {
"type": "boolean"
}
},
"additionalProperties": false
},
"aliasId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Start a topic brief or continue a saved Brief with continuesBriefId and continuationId. The saved version supplies series guidance and its proven evidence source. Preserve backend readiness, budget and idempotency. May consume credits. Poll socialseal_get_brief_run with the returned runId; no social publishing or persistent account tracker. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| prompt | string | null | |
| brandId | string | null | |
| topicId | string | |
| pillarId | string | null | |
| quoteOnly | boolean | |
| forceRerun | boolean | |
| maxCostUsd | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| outputLocale | string | null |
Ask the specified queries of one engine, one run per query: google_ai (Google's AI Overview, the default), chatgpt, gemini or claude. Each answer is kept with the pages it cites and the brands it names. A Claude query costs twice a Google AI, ChatGPT or Gemini query; quote first with quoteOnly. Returns runIds (one numeric runId per query; runId is the first); poll socialseal_get_tool_status with kind=google_ai_run for each and read results after completion. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| engine | string | The engine that answers; google_ai when omitted. One engine per call. |
| queries* | string | array | |
| quoteOnly | boolean | |
| maxCostUsd | string | |
| countryCode | string | Two-letter market; us when omitted. Each engine is asked only in its own markets: any other is refused before any charge with UNSUPPORTED_PLATFORM_REGION and the engine's supportedMarkets. |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| idempotencyKey |
Start bounded keyword expansion for the specified subject/market. May incur collection/analysis cost under existing backend controls. Returns runId; poll socialseal_get_tool_status with kind=journey_run. Creates an execution, not an ongoing tracker. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| locale | string | |
| region* | string | |
| subject* | string | |
| quoteOnly | boolean | |
| skipCache | boolean | |
| maxCostUsd | string | |
| maxKeywords | integer | |
| subjectType* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
Receive one complete evidence-backed Visibility Check per eligible user for a business, its website and market. Requires the business's own website (not a social profile or link-in-bio page); ask the user for it before calling; without one, offer the direct creator, video or search actions instead. Uses normal login, including consumer email. This is optional: a specific creator, video or export request should use its own action directly. Returns a durable operation; read candidate themes, continue with stored IDs, then retrieve the complete report: submission or partial evidence is not completion. Failed or partial-only reports restore eligibility; reconnects for the same brand, market, platform and website reuse released work. If the free check is already allocated to a different brand, market, platform or website, status is complimentary_in_use: nothing new was started, so tell the user which brand, market and website hold it (operationId, locator, market, targetWebsiteUrl) and never present that report as the requested one.
| Argument | Type | Description |
|---|---|---|
| market* | string | Country code for the audience being researched. |
| locator* | string | |
| platform | string | |
| workspaceId* | string | Resolve the user's authorized workspace; reuse the only workspace without asking for its ID. |
| idempotencyKey* | string | |
Copy existing tracked keyword associations into the keyword registry; does not run provider collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Create only the explicitly requested ongoing account commitment. May schedule provider refresh and incur collection cost under existing controls. Use creator reads for a one-off evaluation. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| items | array | Batch searches. Each item may include value, region, platform, and topicRefs. |
| value* | string | The specified platform account handle or URL. |
| region | string | |
| command | object | Canonical preview command snapshot. Send this on execute so automatic assignments are not reclassified. |
| brandIds | array | |
| platform* | string | Supported tracking platform key, such as instagram, tiktok or youtube; the backend rejects unsupported platforms. |
| topicMode | string | explicit assigns named Topic refs; auto classifies omitted Topics; mixed keeps explicit rows and classifies the rest. Default auto. |
Create the explicitly requested search/hashtag commitment. Active searches require Topic resolution: pass topicDefinitions and topicRefs, or omit them for automatic organisation. Unambiguous single-search automatic results preview and execute together; ambiguous results return TOPIC_INPUT_REQUIRED without activating. May schedule collection and incur cost under existing controls. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| type* | string | |
| items | array | Batch searches. Each item may include value, region, platform, and topicRefs. |
| value* | string | |
| region | string | |
| command | object | Canonical preview command snapshot. Send this on execute so automatic assignments are not reclassified. |
| brandIds | array | |
| platform* | string | Supported tracking platform key, such as instagram, tiktok or youtube; the backend rejects unsupported platforms. |
Update a comparison set's name or description; no collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| group* | object | |
| groupId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"groupId",
"group"
],
"properties": {
"group": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string"
}
},
"additionalProperties": false
},
"groupId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Save the requested creator-brief edits as a new version without modifying or deleting prior versions. Unspecified fields, evidence lineage and pinned context are preserved; supplied arrays replace that field in the new version (null arrays clear it). Supply briefId or opportunityKey. A stale base version is rejected. Reuse editId on retry; an unchanged retry can return NO_CHANGES before replaying the original result, so read the saved brief to verify its version. Without editId, retries may create additional versions. A successful write returns the saved brief, version and deduplication status. No collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| edits* | object | |
| editId | string | |
| brandId | string | null | |
| briefId | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| opportunityKey | string | |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
Update the requested keyword record and associations; no provider collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| patch* | object | |
| keywordId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"keywordId",
"patch"
],
"properties": {
"patch": {
"type": "object",
"properties": {
"term": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"active": {
"type": "boolean"
},
"locale": {
"type": "string",
"maxLength": 24
},
"region": {
"type": "string",
"maxLength": 16
},
"source": {
"type": "string",
"maxLength": 80
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"sources": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"minLength": 1
},
"maxItems": 20
},
"language": {
"type": "string",
"maxLength": 16
},
"intentIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"localeKey": {
"type": "string",
"maxLength": 24
},
"pillarIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"productId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"personaIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"provenance": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"opportunityKey": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"keywordId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Apply the requested patch to the selected keyword IDs; no provider collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| patch* | object | |
| keywordIds* | array | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"keywordIds",
"patch"
],
"properties": {
"patch": {
"type": "object",
"properties": {
"term": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"active": {
"type": "boolean"
},
"locale": {
"type": "string",
"maxLength": 24
},
"region": {
"type": "string",
"maxLength": 16
},
"source": {
"type": "string",
"maxLength": 80
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"sources": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"minLength": 1
},
"maxItems": 20
},
"language": {
"type": "string",
"maxLength": 16
},
"intentIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"localeKey": {
"type": "string",
"maxLength": 24
},
"pillarIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"productId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"personaIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"provenance": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"opportunityKey": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"keywordIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 100,
"minItems": 1
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Apply requested changes to a saved strategy persona; no provider collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| persona* | object | |
| personaId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"personaId",
"persona"
],
"properties": {
"persona": {
"type": "object",
"properties": {
"label": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"active": {
"type": "boolean"
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"languages": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"description": "BCP-47 locale tag, e.g. en-SG or zh-Hans; backend validates tags."
},
"maxItems": 50
},
"description": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 4000
},
{
"type": "null"
}
]
},
"originRegions": {
"type": "array",
"items": {
"type": "string",
"maxLength": 16,
"minLength": 1
},
"maxItems": 50
}
},
"additionalProperties": false
},
"personaId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}Update the requested group name, description or refresh schedule; scheduling can affect future collection. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| group_id* | integer | |
| description | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| next_refresh_at | string | |
| refresh_frequency | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"group_id"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"group_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": {
"type": "string"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"next_refresh_at": {
"type": "string",
"minLength": 1
},
"refresh_frequency": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}Update the requested item configuration; scheduling changes can affect future collection cost. is_active: true resumes a paused item (same rules as socialseal_resume_tracking_item); pausing is not supported. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| item_id* | integer | |
| is_active | boolean | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| next_refresh_at | string | |
| refresh_frequency | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"item_id"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"item_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"is_active": {
"type": "boolean"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"next_refresh_at": {
"type": "string",
"minLength": 1
},
"refresh_frequency": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}Replace the current workspace note with the supplied content as a new version, mark the previous version superseded and rebuild core context. Prior versions remain stored. Returns the new note and superseded note identifier. No provider collection cost. Changes only the requested workspace state. Backend authorization, validation, pricing, balance and idempotency controls remain authoritative; tool selection does not authorize additional work.
| Argument | Type | Description |
|---|---|---|
| note* | object | |
| noteId* | string | |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"noteId",
"note"
],
"properties": {
"note": {
"type": "object",
"required": [
"type",
"bodyMd"
],
"properties": {
"key": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"tags": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"type": {
"enum": [
"fact",
"preference",
"decision",
"constraint",
"workflow",
"task"
],
"type": "string"
},
"title": {
"type": "string",
"maxLength": 200
},
"bodyMd": {
"type": "string",
"maxLength": 50000,
"minLength": 1
},
"confidence": {
"type": "number",
"maximum": 1,
"minimum": 0
},
"importance": {
"type": "number",
"maximum": 1,
"minimum": 0
},
"provenance": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"pinnedToCore": {
"type": "boolean"
},
"lastConfirmedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"noteId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"group_id"
],
"properties": {
"items": {
"type": "array",
"items": {},
"description": "Search or tracking payloads with optional topicRefs."
},
"group_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"item_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"topicMode": {
"enum": [
"explicit",
"auto",
"mixed"
],
"type": "string"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"idempotencyKey": {
"type": "string",
"minLength": 1
},
"planFingerprint": {
"type": "string",
"minLength": 1
},
"topicDefinitions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
},
"allowCreateTopics": {
"type": "boolean"
}
},
"additionalProperties": false
}| string |
| revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"quoteOnly": {
"type": "boolean"
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$"
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}| Opportunity UUID returned by Monitor, Study or Create. Supply this or opportunityKey. |
| idempotencyKey | string |
| opportunityKey | string | Deprecated: use opportunityId. Accepted for one catalogue version. |
| trackingItemIds | array | null |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"briefId",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"region": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 64,
"minLength": 1
},
{
"type": "null"
}
]
},
"briefId": {
"type": "string",
"format": "uuid"
},
"quoteOnly": {
"type": "boolean"
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$"
},
"publishedAt": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
]
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"opportunityId": {
"type": "string",
"format": "uuid",
"description": "Opportunity UUID returned by Monitor, Study or Create. Supply this or opportunityKey."
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"opportunityKey": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Deprecated: use opportunityId. Accepted for one catalogue version."
},
"trackingItemIds": {
"type": [
"array",
"null"
],
"anyOf": [
{
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"minItems": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}| platform* | string |
| quoteOnly | boolean | Return the price without collecting: credits for subscription workspaces, USD for prepaid. |
| maxCostUsd | string | Prepaid workspaces only: refuse with CALLER_LIMIT_EXCEEDED above this USD price. |
| workspaceId* | string | Workspace whose credits or funds pay for the collection. Ask the user which one when they have several. |
| idempotencyKey* | string | Reuse this key after timeouts or retries. A new key starts a new billable collection. |
| recentPostCount | integer | Instagram: latest posts to collect (default 5). |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
| maxProviderRequests | integer | TikTok, required: provider request budget, including the profile and each page. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"platform",
"target",
"workspaceId",
"idempotencyKey"
],
"properties": {
"endAt": {
"type": "string",
"format": "date-time",
"description": "TikTok, required: end of the publication window."
},
"target": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Named account profile URL or @handle; not a search keyword or post URL."
},
"brandId": {
"type": "string",
"format": "uuid",
"description": "Instagram: existing workspace brand for partnership context."
},
"startAt": {
"type": "string",
"format": "date-time",
"description": "TikTok, required: start of the publication window [startAt,endAt)."
},
"platform": {
"enum": [
"instagram",
"tiktok"
],
"type": "string"
},
"quoteOnly": {
"type": "boolean",
"description": "Return the price without collecting: credits for subscription workspaces, USD for prepaid."
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$",
"description": "Prepaid workspaces only: refuse with CALLER_LIMIT_EXCEEDED above this USD price."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Workspace whose credits or funds pay for the collection. Ask the user which one when they have several."
},
"idempotencyKey": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Reuse this key after timeouts or retries. A new key starts a new billable collection."
},
"recentPostCount": {
"type": "integer",
"description": "Instagram: latest posts to collect (default 5).",
"exclusiveMinimum": 0
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
},
"maxProviderRequests": {
"type": "integer",
"minimum": 2,
"description": "TikTok, required: provider request budget, including the profile and each page."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"brand_id": {
"type": "string",
"format": "uuid"
},
"platform": {
"type": "string",
"minLength": 1
},
"locale_key": {
"type": "string",
"maxLength": 35,
"minLength": 1,
"description": "Optional language-market key such as en-SG; part of the group identity."
},
"description": {
"type": "string"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"next_refresh_at": {
"type": "string",
"minLength": 1
},
"refresh_frequency": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}| explicit assigns named Topic refs; auto classifies omitted Topics; mixed keeps explicit rows and classifies the rest. Default auto. |
| topicRefs | array | Topic refs from topicDefinitions to assign to a single search. |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| idempotencyKey* | string | Stable idempotency key for this plan. |
| next_refresh_at | string |
| planFingerprint* | string | Fingerprint from preview_search_activation. |
| topicDefinitions | array | Existing or inline-create Topic definitions with stable refs. Several searches may share one new Topic ref. |
| allowCreateTopics | boolean | When topicMode is auto or mixed, whether automatic organisation may propose new Topics. Default true. |
| refresh_frequency | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"platform",
"idempotencyKey",
"planFingerprint"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"keyword",
"hashtag"
],
"type": "string"
},
"items": {
"type": "array",
"items": {},
"description": "Batch searches. Each item may include value, region, platform, and topicRefs."
},
"value": {
"type": "string",
"minLength": 1
},
"region": {
"type": "string",
"minLength": 1
},
"command": {
"type": "object",
"description": "Canonical preview command snapshot. Send this on execute so automatic assignments are not reclassified.",
"additionalProperties": {}
},
"brandIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"platform": {
"type": "string",
"minLength": 1,
"description": "Supported tracking platform key, such as instagram, tiktok or youtube; the backend rejects unsupported platforms."
},
"topicMode": {
"enum": [
"explicit",
"auto",
"mixed"
],
"type": "string",
"description": "explicit assigns named Topic refs; auto classifies omitted Topics; mixed keeps explicit rows and classifies the rest. Default auto."
},
"topicRefs": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "Topic refs from topicDefinitions to assign to a single search."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Stable idempotency key for this plan."
},
"next_refresh_at": {
"type": "string",
"minLength": 1
},
"planFingerprint": {
"type": "string",
"minLength": 1,
"description": "Fingerprint from preview_search_activation."
},
"topicDefinitions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Existing or inline-create Topic definitions with stable refs. Several searches may share one new Topic ref."
},
"allowCreateTopics": {
"type": "boolean",
"description": "When topicMode is auto or mixed, whether automatic organisation may propose new Topics. Default true."
},
"refresh_frequency": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}| string |
| planFingerprint | string |
| sourcePlatforms | array | Platforms to track the selected searches on, for example ["tiktok"]. |
| confirmedScopeFingerprint | string | Required only when the activation preview returned confirmationRequired; echo the reviewed planFingerprint once after the principal confirms the aggregate scope, reusing the same idempotencyKey. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"description": "Optional complete canonical activateSearches body; explicit fields override it.",
"additionalProperties": {}
},
"cadence": {
"enum": [
"daily",
"weekly",
"monthly"
],
"type": "string",
"description": "Refresh cadence; defaults to weekly. Each refresh is charged when it collects."
},
"handoffId": {
"type": "string",
"format": "uuid"
},
"topicName": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Topic the selected searches are tracked under; an existing Topic with this name is reused."
},
"selectionId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"actorContext": {
"type": "object",
"additionalProperties": {}
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"planFingerprint": {
"type": "string",
"minLength": 1
},
"sourcePlatforms": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Platforms to track the selected searches on, for example [\"tiktok\"]."
},
"confirmedScopeFingerprint": {
"type": "string",
"minLength": 1,
"description": "Required only when the activation preview returned confirmationRequired; echo the reviewed planFingerprint once after the principal confirms the aggregate scope, reusing the same idempotencyKey."
}
},
"additionalProperties": false
}| idempotencyKey |
| string |
| newCandidateTopic | object | null |
| targetMemberships | array |
| expectedRevisionId | string | null |
| targetCandidateTopicId | string | null |
| selectedCandidateTopicId | string | null |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"description": "Optional complete canonical applyInterpretationCorrection body; explicit fields override it.",
"additionalProperties": {}
},
"labels": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
},
"status": {
"enum": [
"proposed",
"accepted"
],
"type": "string"
},
"lineageId": {
"type": "string",
"format": "uuid"
},
"operation": {
"enum": [
"rename",
"create",
"accepted_move",
"secondary_membership",
"split",
"merge",
"retire"
],
"type": "string"
},
"snapshotId": {
"type": "string",
"format": "uuid"
},
"memberships": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"actorContext": {
"type": "object",
"additionalProperties": {}
},
"changeSummary": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"newCandidateTopic": {
"type": [
"object",
"null"
],
"anyOf": [
{
"type": "object",
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"targetMemberships": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
},
"expectedRevisionId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"targetCandidateTopicId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"selectedCandidateTopicId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}| selectionId | string |
| workspaceId | string |
| actorContext | object |
| afterSnapshotId | string |
| beforeSnapshotId | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"description": "Optional canonical read body; explicit fields override it.",
"additionalProperties": {}
},
"page": {
"type": "integer",
"minimum": 1
},
"sort": {
"enum": [
"created_desc",
"version_desc",
"display_order_asc"
],
"type": "string"
},
"runId": {
"type": "string",
"format": "uuid"
},
"outcome": {
"enum": [
"complete",
"partial",
"thin",
"missing_data",
"failed"
],
"type": "string"
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1
},
"resource": {
"enum": [
"lineage",
"snapshot",
"run",
"selection",
"compare"
],
"type": "string",
"default": "lineage"
},
"lineageId": {
"type": "string",
"format": "uuid"
},
"snapshotId": {
"type": "string",
"format": "uuid"
},
"selectionId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"actorContext": {
"type": "object",
"additionalProperties": {}
},
"afterSnapshotId": {
"type": "string",
"format": "uuid"
},
"beforeSnapshotId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
}| actorContext |
| object |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"description": "Optional canonical workspaceOverview fields.",
"additionalProperties": {}
},
"page": {
"type": "integer",
"minimum": 1
},
"sort": {
"enum": [
"created_desc",
"version_desc",
"display_order_asc"
],
"type": "string"
},
"view": {
"enum": [
"summary",
"full"
],
"type": "string",
"description": "summary (default) omits snapshot diagnostics and evidence manifests; read one snapshot with socialseal_explore_get for full evidence."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1
},
"outcome": {
"enum": [
"complete",
"partial",
"thin",
"missing_data",
"failed"
],
"type": "string"
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Optional workspace UUID. Reads resolve the live configured workspace when omitted."
},
"actorContext": {
"type": "object",
"additionalProperties": {}
}
},
"additionalProperties": false
}| string |
| Required only when a refresh admission rejected with EXPLORE_SCOPE_CONFIRMATION_REQUIRED; echo the rejected scopeFingerprint once after the principal confirms the aggregate scope, reusing the same idempotencyKey. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"description": "Optional complete canonical refreshLineage body; explicit fields override it.",
"additionalProperties": {}
},
"lineageId": {
"type": "string",
"format": "uuid"
},
"quoteOnly": {
"type": "boolean"
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$"
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"actorContext": {
"type": "object",
"additionalProperties": {}
},
"evidenceWindow": {
"type": "object",
"required": [
"startAt",
"endAt"
],
"properties": {
"endAt": {
"type": "string",
"format": "date-time"
},
"startAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"providerBasket": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"confirmedScopeFingerprint": {
"type": "string",
"minLength": 1,
"description": "Required only when a refresh admission rejected with EXPLORE_SCOPE_CONFIRMATION_REQUIRED; echo the rejected scopeFingerprint once after the principal confirms the aggregate scope, reusing the same idempotencyKey."
}
},
"additionalProperties": false
}| interpretationRevisionId | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"description": "Optional complete canonical createSelection body; explicit fields override it.",
"additionalProperties": {}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"itemKind",
"targetId",
"inclusionState"
],
"properties": {
"itemKind": {
"enum": [
"search_term",
"candidate_topic",
"evidence_ref",
"context_ref"
],
"type": "string"
},
"targetId": {
"type": "string",
"format": "uuid"
},
"inclusionState": {
"enum": [
"included",
"excluded"
],
"type": "string"
}
},
"additionalProperties": false
},
"minItems": 1
},
"lineageId": {
"type": "string",
"format": "uuid"
},
"snapshotId": {
"type": "string",
"format": "uuid"
},
"intendedUse": {
"type": "string",
"minLength": 1
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"actorContext": {
"type": "object",
"additionalProperties": {}
},
"userQuestion": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
]
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"intendedDestination": {
"enum": [
"monitor",
"study",
"create",
"find_creators",
"seal",
"deliverable_share"
],
"type": "string"
},
"continuationMetadata": {
"type": "object",
"additionalProperties": {}
},
"interpretationRevisionId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
}| actorContext |
| object |
| evidenceWindow | object |
| idempotencyKey | string |
| providerBasket | array |
| intentFingerprint | string | null |
| previewFingerprint | string |
| confirmedScopeFingerprint | string | Required only when the start preview or a rejected start returned confirmationRequired; echo the reviewed planFingerprint once after the principal confirms the aggregate scope. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"description": "Optional complete canonical startLineage body; explicit fields override it.",
"additionalProperties": {}
},
"anchor": {
"type": "object",
"additionalProperties": {}
},
"quoteOnly": {
"type": "boolean"
},
"sourceRef": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
]
},
"marketCode": {
"type": "string",
"minLength": 1
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$"
},
"sourceKind": {
"enum": [
"manual",
"api",
"visibility_check_import",
"migration"
],
"type": "string"
},
"languageTag": {
"type": "string",
"minLength": 1
},
"workspaceId": {
"type": "string",
"format": "uuid"
},
"actorContext": {
"type": "object",
"additionalProperties": {}
},
"evidenceWindow": {
"type": "object",
"required": [
"startAt",
"endAt"
],
"properties": {
"endAt": {
"type": "string",
"format": "date-time"
},
"startAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"providerBasket": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"intentFingerprint": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
]
},
"previewFingerprint": {
"type": "string",
"minLength": 1
},
"confirmedScopeFingerprint": {
"type": "string",
"minLength": 1,
"description": "Required only when the start preview or a rejected start returned confirmationRequired; echo the reviewed planFingerprint once after the principal confirms the aggregate scope."
}
},
"additionalProperties": false
}| Required explicit workspace UUID (unless body.workspaceId is provided). Workspace defaults are never used for exports. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"properties": {
"format": {
"enum": [
"csv",
"json",
"markdown",
"html",
"excel_data"
],
"type": "string",
"description": "Export format. search_results_enriched supports only \"csv\"."
},
"payload": {
"type": "object",
"description": "Required report payload. For search_results_enriched, include payload.groupIds with numeric tracking group ids.",
"additionalProperties": {}
},
"reportType": {
"enum": [
"keyword_universe",
"cluster_insights",
"creator_signatures",
"post_publish",
"quick_audit",
"search_results_enriched"
],
"type": "string",
"description": "Required report type. Use \"search_results_enriched\" for ranked discoverability/search results. Search rows describe videos surfaced for selected queries at capture time, not search volume or total market demand. Within one platform, market and capture window, result counts, rank and views remain valid relative demand signals for comparing queries; when asked to prioritise, rank with them and label confidence instead of declining. Region is the collection market, not verified viewer geography. Views/likes/saves are video engagement snapshots, not engagement attributable to that query or gains during the export window. State query/platform/market/date scope and coverage; deduplicate videos before aggregating across queries. Define rate denominators and preserve missing values as unknown. Inspect relevant video evidence before recommending a creative treatment."
}
},
"description": "Report export body. Include reportType, format, and payload.",
"additionalProperties": true
},
"format": {
"enum": [
"csv",
"json",
"markdown",
"html",
"excel_data"
],
"type": "string",
"description": "Export format. search_results_enriched supports only \"csv\"."
},
"payload": {
"type": "object",
"description": "Required report payload. For search_results_enriched, include payload.groupIds with numeric tracking group ids.",
"additionalProperties": {}
},
"reportType": {
"enum": [
"keyword_universe",
"cluster_insights",
"creator_signatures",
"post_publish",
"quick_audit",
"search_results_enriched"
],
"type": "string",
"description": "Required report type. Use \"search_results_enriched\" for ranked discoverability/search results."
},
"workspaceId": {
"type": "string",
"description": "Required explicit workspace UUID (unless body.workspaceId is provided). Workspace defaults are never used for exports."
}
},
"additionalProperties": false
}| integer | string |
| Convenience alias for body.tracking_item_id. |
| tracking_item_id | integer | string | Convenience field for body.tracking_item_id. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"type": "object",
"properties": {
"groupId": {
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "string",
"minLength": 1
}
],
"description": "CamelCase alias for group_id, a numeric tracking_group id."
},
"group_id": {
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "string",
"minLength": 1
}
],
"description": "Numeric tracking_group id for the legacy tracking CSV export. Pair it with the workspaceId from the same group lookup."
},
"timePeriod": {
"type": "string",
"minLength": 1,
"description": "CamelCase alias for time_period; use \"30d\" unless the user asked for another window."
},
"time_period": {
"type": "string",
"minLength": 1,
"description": "Required legacy export window, for example \"30d\"."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Workspace that owns the selected group or tracking item. Reuse the workspaceId from the lookup that returned the ID."
},
"workspace_id": {
"type": "string",
"format": "uuid",
"description": "Snake-case alias for workspaceId."
},
"trackingItemId": {
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "string",
"minLength": 1
}
],
"description": "CamelCase alias for tracking_item_id."
},
"tracking_item_id": {
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "string",
"minLength": 1
}
],
"description": "Tracking item id for a single-item legacy tracking CSV export."
}
},
"description": "Legacy export body. Provide group_id or tracking_item_id, plus required time_period such as \"30d\".",
"additionalProperties": true
},
"groupId": {
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "string",
"minLength": 1
}
],
"description": "Convenience alias for body.group_id, a numeric tracking_group id."
},
"group_id": {
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "string",
"minLength": 1
}
],
"description": "Convenience field for body.group_id, a numeric tracking_group id."
},
"timePeriod": {
"type": "string",
"minLength": 1,
"description": "Required legacy export window unless supplied in body.time_period, for example \"30d\"."
},
"time_period": {
"type": "string",
"minLength": 1,
"description": "Required legacy export window unless supplied in body.timePeriod, for example \"30d\"."
},
"workspaceId": {
"type": "string",
"description": "Required explicit workspace from the same lookup that returned the selected group or tracking item (unless body.workspaceId is provided). Workspace defaults are never used for exports."
},
"trackingItemId": {
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "string",
"minLength": 1
}
],
"description": "Convenience alias for body.tracking_item_id."
},
"tracking_item_id": {
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "string",
"minLength": 1
}
],
"description": "Convenience field for body.tracking_item_id."
}
},
"additionalProperties": false
}| Authorized workspace for this requested write; discover accessible context first. |
| frameStrategy | string |
| ensureAnalysis | boolean |
| idempotencyKey | string |
| signedUrlSeconds | integer |
| includeRawAnalysis | boolean |
| includeSourceVideo | boolean |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"anyOf": [
{
"type": "object",
"required": [
"videoUid"
],
"properties": {
"videoUid": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"platformVideoId"
],
"properties": {
"platformId": {
"type": "integer",
"exclusiveMinimum": 0
},
"platformVideoId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"minLength": 1
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"searchResultId"
],
"properties": {
"searchResultId": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"videoId"
],
"properties": {
"videoId": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"maxItems": 25,
"minItems": 1
},
"quoteOnly": {
"type": "boolean"
},
"frameCount": {
"type": "integer",
"maximum": 5,
"exclusiveMinimum": 0
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"frameStrategy": {
"enum": [
"brief_shots",
"quartiles"
],
"type": "string"
},
"ensureAnalysis": {
"type": "boolean"
},
"idempotencyKey": {
"type": "string",
"minLength": 1
},
"signedUrlSeconds": {
"type": "integer",
"maximum": 7200,
"minimum": 60,
"exclusiveMinimum": 0
},
"includeRawAnalysis": {
"type": "boolean"
},
"includeSourceVideo": {
"type": "boolean"
}
},
"additionalProperties": false
}| string |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| rightsAttested* | boolean |
| durationSeconds | number | null |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"clipId",
"fileName",
"storagePath",
"mimeType",
"sizeBytes",
"rightsAttested"
],
"properties": {
"width": {
"type": [
"integer",
"null"
],
"anyOf": [
{
"type": "integer",
"maximum": 8192,
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"clipId": {
"type": "string",
"format": "uuid"
},
"height": {
"type": [
"integer",
"null"
],
"anyOf": [
{
"type": "integer",
"maximum": 8192,
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"fileName": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"mimeType": {
"enum": [
"video/mp4",
"video/quicktime",
"video/webm"
],
"type": "string"
},
"quoteOnly": {
"type": "boolean"
},
"sizeBytes": {
"type": "integer",
"maximum": 52428800,
"exclusiveMinimum": 0
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$"
},
"posterPath": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
]
},
"storagePath": {
"type": "string",
"minLength": 1
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"rightsAttested": {
"type": "boolean",
"const": true
},
"durationSeconds": {
"type": [
"number",
"null"
],
"anyOf": [
{
"type": "number",
"maximum": 3600,
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}| maxCostUsd | string |
| timePeriod | string |
| platformIds | array |
| previewOnly | boolean |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| idempotencyKey | string |
| opportunityKey* | string |
| readinessRunId | string |
| pinnedVideoUids | array |
| retrievalPrompt | string |
| trackingGroupId | integer |
| excludedVideoUids | array |
| competitorBrandIds | array |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
| videoSelectionMode | string |
| allowWarningOverride | boolean |
| promotedCandidateTarget | integer |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"opportunityKey",
"scopeType"
],
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"listId": {
"type": "string",
"format": "uuid"
},
"region": {
"type": "string",
"maxLength": 10,
"minLength": 1
},
"topicId": {
"type": "string",
"format": "uuid"
},
"language": {
"type": "string",
"maxLength": 16,
"minLength": 1
},
"pillarId": {
"type": "string",
"format": "uuid"
},
"quoteOnly": {
"type": "boolean"
},
"scopeType": {
"enum": [
"topic",
"competitor",
"tracking_group",
"manual",
"list"
],
"type": "string"
},
"videoUids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$"
},
"timePeriod": {
"type": "string",
"maxLength": 20,
"minLength": 1
},
"platformIds": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"maxItems": 10
},
"previewOnly": {
"type": "boolean"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"opportunityKey": {
"type": "string",
"maxLength": 128,
"minLength": 8
},
"readinessRunId": {
"type": "string",
"format": "uuid"
},
"pinnedVideoUids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"retrievalPrompt": {
"type": "string",
"maxLength": 2000,
"minLength": 1
},
"trackingGroupId": {
"type": "integer",
"exclusiveMinimum": 0
},
"excludedVideoUids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"competitorBrandIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
},
"videoSelectionMode": {
"enum": [
"merge",
"manual_only"
],
"type": "string"
},
"allowWarningOverride": {
"type": "boolean"
},
"promotedCandidateTarget": {
"type": "integer",
"maximum": 24,
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}| videoUids | array |
| maxCostUsd | string |
| timePeriod | string |
| blueprintId | string |
| platformIds | array |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| brandContext | object |
| opportunityId | string | Opportunity UUID returned by Monitor, Study or Create. Supply this or opportunityKey. |
| idempotencyKey | string |
| opportunityKey | string | Deprecated: use opportunityId. Accepted for one catalogue version. |
| readinessRunId | string |
| pinnedVideoUids | array |
| retrievalPrompt | string |
| trackingGroupId | integer |
| blueprintVersion | integer |
| excludedVideoUids | array |
| competitorBrandIds | array |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
| videoSelectionMode | string |
| promotedCandidateTarget | integer |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId"
],
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"listId": {
"type": "string",
"format": "uuid"
},
"region": {
"type": "string",
"maxLength": 10,
"minLength": 1
},
"topicId": {
"type": "string",
"format": "uuid"
},
"language": {
"type": "string",
"maxLength": 16,
"minLength": 1
},
"pillarId": {
"type": "string",
"format": "uuid"
},
"quoteOnly": {
"type": "boolean"
},
"scopeType": {
"enum": [
"topic",
"competitor",
"tracking_group"
],
"type": "string"
},
"videoUids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$"
},
"timePeriod": {
"type": "string",
"maxLength": 20,
"minLength": 1
},
"blueprintId": {
"type": "string",
"format": "uuid"
},
"platformIds": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"maxItems": 10
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"brandContext": {
"type": "object",
"properties": {
"notes": {
"type": "string",
"maxLength": 2000,
"minLength": 1,
"description": "Concise approved audience needs, product/service facts with source references, voice/CTA, exclusions and production constraints. Distinguish verified facts from unknowns. This field does not automatically retrieve project files or verify claims."
},
"locale": {
"type": "string",
"maxLength": 20,
"minLength": 1
},
"platform": {
"type": "string",
"maxLength": 20,
"minLength": 1
},
"brandName": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"productName": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"campaignGoal": {
"type": "string",
"maxLength": 500,
"minLength": 1
}
},
"additionalProperties": false
},
"opportunityId": {
"type": "string",
"format": "uuid",
"description": "Opportunity UUID returned by Monitor, Study or Create. Supply this or opportunityKey."
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"opportunityKey": {
"type": "string",
"maxLength": 128,
"minLength": 8,
"description": "Deprecated: use opportunityId. Accepted for one catalogue version."
},
"readinessRunId": {
"type": "string",
"format": "uuid"
},
"pinnedVideoUids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"retrievalPrompt": {
"type": "string",
"maxLength": 2000,
"minLength": 1
},
"trackingGroupId": {
"type": "integer",
"exclusiveMinimum": 0
},
"blueprintVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"excludedVideoUids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"competitorBrandIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
},
"videoSelectionMode": {
"enum": [
"merge",
"manual_only"
],
"type": "string"
},
"promotedCandidateTarget": {
"type": "integer",
"maximum": 24,
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}| strategyRevisionId |
| string |
| revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"briefId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"historyLimit": {
"type": "integer",
"maximum": 20,
"exclusiveMinimum": 0
},
"opportunityId": {
"type": "string",
"format": "uuid",
"description": "Opportunity UUID returned by Monitor, Study or Create. Supply this or opportunityKey."
},
"includeHistory": {
"type": "boolean"
},
"opportunityKey": {
"type": "string",
"maxLength": 128,
"minLength": 8,
"description": "Deprecated: use opportunityId. Accepted for one catalogue version."
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}| opportunityKey | string | Deprecated: use opportunityId. Accepted for one catalogue version. |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"region": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 64,
"minLength": 1
},
{
"type": "null"
}
]
},
"briefId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Exact saved Brief version; omit only for an explicit opportunity-wide read."
},
"platforms": {
"type": [
"array",
"null"
],
"anyOf": [
{
"type": "array",
"items": {
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "string",
"minLength": 1
}
]
},
"maxItems": 20
},
{
"type": "null"
}
]
},
"weekStart": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
]
},
"windowWeeks": {
"type": [
"integer",
"null"
],
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"opportunityId": {
"type": "string",
"format": "uuid",
"description": "Opportunity UUID returned by Monitor, Study or Create. Supply this or opportunityKey."
},
"opportunityKey": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Deprecated: use opportunityId. Accepted for one catalogue version."
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}| workspaceId | string | Accessible workspace; uses the configured default when omitted. No tracking group required. |
| recentPostCount | integer | Requested latest account posts, including images, carousels and videos. Coverage may be incomplete. |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"target",
"platform"
],
"properties": {
"target": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Named Instagram profile URL or @handle; not a search keyword or post URL."
},
"brandId": {
"type": "string",
"format": "uuid",
"description": "Optional existing workspace brand for partnership context. Missing brand evidence does not block metrics."
},
"platform": {
"type": "string",
"const": "instagram",
"description": "Stored Instagram evidence only. To collect any account, Instagram or TikTok, use socialseal_collect_account."
},
"freshness": {
"enum": [
"stored",
"fresh"
],
"type": "string",
"default": "stored",
"description": "Stored evidence read. Fresh requests return FRESH_COLLECTION_REQUIRED alongside stored evidence; use the separate bounded collect action."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Accessible workspace; uses the configured default when omitted. No tracking group required."
},
"recentPostCount": {
"type": "integer",
"default": 5,
"description": "Requested latest account posts, including images, carousels and videos. Coverage may be incomplete.",
"exclusiveMinimum": 0
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}| workspaceId | string | Accessible workspace; uses the configured default when omitted. No tracking group required. |
| recentPostCount | integer | Requested latest account posts, including images, carousels and videos. Coverage may be incomplete. |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"target",
"platform"
],
"properties": {
"target": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Named Instagram profile URL or @handle; not a search keyword or post URL."
},
"brandId": {
"type": "string",
"format": "uuid",
"description": "Optional existing workspace brand for partnership context. Missing brand evidence does not block metrics."
},
"platform": {
"type": "string",
"const": "instagram",
"description": "Stored Instagram evidence only. To collect any account, Instagram or TikTok, use socialseal_collect_account."
},
"freshness": {
"enum": [
"stored",
"fresh"
],
"type": "string",
"default": "stored",
"description": "Stored evidence read. Fresh requests return FRESH_COLLECTION_REQUIRED alongside stored evidence; use the separate bounded collect action."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Accessible workspace; uses the configured default when omitted. No tracking group required."
},
"recentPostCount": {
"type": "integer",
"default": 5,
"description": "Requested latest account posts, including images, carousels and videos. Coverage may be incomplete.",
"exclusiveMinimum": 0
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}| boolean |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"exclusiveMinimum": 0
},
"query": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"runId": {
"type": "integer",
"exclusiveMinimum": 0
},
"engine": {
"enum": [
"google_ai",
"chatgpt",
"gemini",
"claude"
],
"type": "string",
"description": "Only this engine's answers; every engine's when omitted."
},
"offset": {
"type": "integer",
"minimum": 0
},
"skipCache": {
"type": "boolean"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Reuse the authorized default or sole accessible workspace when omitted."
},
"trackingItemId": {
"type": "integer",
"exclusiveMinimum": 0
},
"includeCitations": {
"type": "boolean"
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}| explicit assigns named Topic refs; auto classifies omitted Topics; mixed keeps explicit rows and classifies the rest. Default auto. |
| topicRefs | array | Topic refs from topicDefinitions to assign to a single search. |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| idempotencyKey | string |
| next_refresh_at | string |
| topicDefinitions | array | Existing or inline-create Topic definitions with stable refs. Several searches may share one new Topic ref. |
| allowCreateTopics | boolean | When topicMode is auto or mixed, whether automatic organisation may propose new Topics. Default true. |
| refresh_frequency | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"platform"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"keyword",
"hashtag"
],
"type": "string"
},
"items": {
"type": "array",
"items": {},
"description": "Batch searches. Each item may include value, region, platform, and topicRefs."
},
"value": {
"type": "string",
"minLength": 1
},
"region": {
"type": "string",
"minLength": 1
},
"command": {
"type": "object",
"description": "Canonical preview command snapshot. Send this on execute so automatic assignments are not reclassified.",
"additionalProperties": {}
},
"brandIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"platform": {
"type": "string",
"minLength": 1,
"description": "Supported tracking platform key, such as instagram, tiktok or youtube; the backend rejects unsupported platforms."
},
"topicMode": {
"enum": [
"explicit",
"auto",
"mixed"
],
"type": "string",
"description": "explicit assigns named Topic refs; auto classifies omitted Topics; mixed keeps explicit rows and classifies the rest. Default auto."
},
"topicRefs": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "Topic refs from topicDefinitions to assign to a single search."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"idempotencyKey": {
"type": "string",
"minLength": 1
},
"next_refresh_at": {
"type": "string",
"minLength": 1
},
"topicDefinitions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Existing or inline-create Topic definitions with stable refs. Several searches may share one new Topic ref."
},
"allowCreateTopics": {
"type": "boolean",
"description": "When topicMode is auto or mixed, whether automatic organisation may propose new Topics. Default true."
},
"refresh_frequency": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"item_id"
],
"properties": {
"endAt": {
"type": "string",
"format": "date-time"
},
"item_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"startAt": {
"type": "string",
"format": "date-time"
},
"quoteOnly": {
"type": "boolean"
},
"maxCostUsd": {
"type": "string",
"pattern": "^\\d+(?:\\.\\d{1,6})?$"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"idempotencyKey": {
"type": "string",
"minLength": 1
},
"recentPostCount": {
"type": "integer",
"exclusiveMinimum": 0
},
"maxProviderRequests": {
"type": "integer",
"minimum": 2
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"runId"
],
"properties": {
"runId": {
"type": "string",
"format": "uuid"
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"quoteOnly": {
"type": "boolean"
},
"forceRerun": {
"type": "boolean"
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"forceFullRerun": {
"type": "boolean"
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"contextFingerprint": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 512,
"minLength": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"opportunityKey",
"summary"
],
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"source": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"status": {
"enum": [
"draft",
"generated",
"missing_data",
"archived"
],
"type": "string"
},
"summary": {
"type": "string",
"maxLength": 20000,
"minLength": 1
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"type",
"label"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"url": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"keyword",
"video",
"creator",
"timeseries",
"doc",
"cluster",
"opportunity",
"coverage",
"generic"
],
"type": "string"
},
"label": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"source": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
]
},
"metadata": {
"type": [
"object",
"null"
],
"anyOf": [
{
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Domain metadata, not additional operation arguments."
},
"metricSnapshot": {
"type": [
"object",
"null"
],
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": [
"string",
"number",
"null"
]
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 200
},
"metadata": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"bestPractices": {
"type": "array",
"items": {
"type": "string",
"maxLength": 20000,
"minLength": 1
},
"maxItems": 60
},
"opportunityKey": {
"type": "string",
"maxLength": 128,
"minLength": 8
}
},
"additionalProperties": false
}| blueprintVersion* |
| integer |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"opportunityKey",
"blueprintId",
"blueprintVersion"
],
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"status": {
"enum": [
"draft",
"generated",
"missing_data",
"archived"
],
"type": "string"
},
"content": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"summary": {
"type": "string",
"maxLength": 20000,
"minLength": 1
},
"metadata": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"rationale": {
"type": "object",
"description": "Domain metadata, not additional operation arguments.",
"additionalProperties": {}
},
"blueprintId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"opportunityKey": {
"type": "string",
"maxLength": 128,
"minLength": 8
},
"blueprintVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}| region | string | Search collection market; does not establish viewer residence or audience demographics. |
| platform | string |
| quoteOnly | boolean | Return the price without starting provider work: credits for subscription workspaces, USD for prepaid. |
| maxCostUsd | string | Optional USD maximum for this search; a higher price is refused with CALLER_LIMIT_EXCEEDED. |
| workspaceId* | string | Authorized workspace for this search; resolve it before starting. |
| idempotencyKey* | string | Generate once per intended search and reuse for retries. Use a new key to refresh results later. |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"query",
"idempotencyKey"
],
"properties": {
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"minimum": 1,
"description": "Fresh-result limit: TikTok 20, Instagram 30, YouTube/Douyin/XHS 50. Default 20. The price uses this requested scope."
},
"query": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"region": {
"type": "string",
"default": "US",
"maxLength": 16,
"minLength": 2,
"description": "Search collection market; does not establish viewer residence or audience demographics."
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube",
"douyin",
"xhs"
],
"type": "string",
"default": "tiktok"
},
"quoteOnly": {
"type": "boolean",
"description": "Return the price without starting provider work: credits for subscription workspaces, USD for prepaid."
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$",
"description": "Optional USD maximum for this search; a higher price is refused with CALLER_LIMIT_EXCEEDED."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this search; resolve it before starting."
},
"idempotencyKey": {
"type": "string",
"format": "uuid",
"description": "Generate once per intended search and reuse for retries. Use a new key to refresh results later."
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}| opportunityId | string | Opportunity UUID returned by Monitor, Study or Create. Supply this or opportunityKey. |
| continuationId | string | Stable UUID for one intentional series member. Reuse for transport retries and paid quotes; choose a new UUID for another member. |
| idempotencyKey | string |
| continuesBriefId | string |
| strategyRevisionId | string | revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId"
],
"properties": {
"prompt": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 4000
},
{
"type": "null"
}
]
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"topicId": {
"type": "string",
"format": "uuid"
},
"pillarId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"quoteOnly": {
"type": "boolean"
},
"forceRerun": {
"type": "boolean"
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"outputLocale": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 35,
"minLength": 2
},
{
"type": "null"
}
]
},
"opportunityId": {
"type": "string",
"format": "uuid",
"description": "Opportunity UUID returned by Monitor, Study or Create. Supply this or opportunityKey."
},
"continuationId": {
"type": "string",
"format": "uuid",
"description": "Stable UUID for one intentional series member. Reuse for transport retries and paid quotes; choose a new UUID for another member."
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"continuesBriefId": {
"type": "string",
"format": "uuid"
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}| string |
| Reuse for PAYG retries; required for a new prepaid operation. |
| searchLanguage | string | Search language code for Google AI, ChatGPT or Gemini (en when omitted). Omit for Claude: an explicit language is refused with UNSUPPORTED_ANSWER_LANGUAGE; write the query in the desired language. Unsupported codes return supportedLanguages. |
| trackingItemId | integer |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"queries"
],
"properties": {
"engine": {
"enum": [
"google_ai",
"chatgpt",
"gemini",
"claude"
],
"type": "string",
"description": "The engine that answers; google_ai when omitted. One engine per call."
},
"queries": {
"type": [
"string",
"array"
],
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1
}
]
},
"quoteOnly": {
"type": "boolean"
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$"
},
"countryCode": {
"type": "string",
"maxLength": 6,
"minLength": 1,
"description": "Two-letter market; us when omitted. Each engine is asked only in its own markets: any other is refused before any charge with UNSUPPORTED_PLATFORM_REGION and the engine's supportedMarkets."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"idempotencyKey": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Reuse for PAYG retries; required for a new prepaid operation."
},
"searchLanguage": {
"type": "string",
"maxLength": 8,
"minLength": 1,
"description": "Search language code for Google AI, ChatGPT or Gemini (en when omitted). Omit for Claude: an explicit language is refused with UNSUPPORTED_ANSWER_LANGUAGE; write the query in the desired language. Unsupported codes return supportedLanguages."
},
"trackingItemId": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}| platformKeys | array |
| seedKeywords | array |
| contentPillars | array |
| idempotencyKey | string | Reuse for PAYG retries; required for a new prepaid operation. |
| includeRejected | boolean |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"subject",
"subjectType",
"region"
],
"properties": {
"locale": {
"type": "string",
"minLength": 1
},
"region": {
"type": "string",
"minLength": 1
},
"subject": {
"type": "string",
"minLength": 1
},
"quoteOnly": {
"type": "boolean"
},
"skipCache": {
"type": "boolean"
},
"maxCostUsd": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,6})?$"
},
"maxKeywords": {
"type": "integer",
"maximum": 200,
"minimum": 10,
"exclusiveMinimum": 0
},
"subjectType": {
"enum": [
"brand",
"property",
"topic"
],
"type": "string"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"platformKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"seedKeywords": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"contentPillars": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"idempotencyKey": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Reuse for PAYG retries; required for a new prepaid operation."
},
"includeRejected": {
"type": "boolean"
}
},
"additionalProperties": false
}| targetWebsiteUrl* |
| string |
| The business's own public website, for example acme.com. Required; social profiles and link-in-bio pages are rejected. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"idempotencyKey",
"locator",
"market",
"targetWebsiteUrl"
],
"properties": {
"market": {
"type": "string",
"pattern": "^[A-Za-z]{2,3}$",
"description": "Country code for the audience being researched."
},
"locator": {
"type": "string",
"maxLength": 512,
"minLength": 1
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube"
],
"type": "string"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Resolve the user's authorized workspace; reuse the only workspace without asking for its ID."
},
"idempotencyKey": {
"type": "string",
"format": "uuid"
},
"targetWebsiteUrl": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The business's own public website, for example acme.com. Required; social profiles and link-in-bio pages are rejected."
}
},
"additionalProperties": false
}| topicRefs | array | Topic refs from topicDefinitions to assign to a single search. |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| idempotencyKey | string |
| next_refresh_at | string |
| topicDefinitions | array | Existing or inline-create Topic definitions with stable refs. Several searches may share one new Topic ref. |
| allowCreateTopics | boolean | When topicMode is auto or mixed, whether automatic organisation may propose new Topics. Default true. |
| refresh_frequency | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"platform",
"value"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"items": {
"type": "array",
"items": {},
"description": "Batch searches. Each item may include value, region, platform, and topicRefs."
},
"value": {
"type": "string",
"minLength": 1,
"description": "The specified platform account handle or URL."
},
"region": {
"type": "string",
"minLength": 1
},
"command": {
"type": "object",
"description": "Canonical preview command snapshot. Send this on execute so automatic assignments are not reclassified.",
"additionalProperties": {}
},
"brandIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"platform": {
"type": "string",
"minLength": 1,
"description": "Supported tracking platform key, such as instagram, tiktok or youtube; the backend rejects unsupported platforms."
},
"topicMode": {
"enum": [
"explicit",
"auto",
"mixed"
],
"type": "string",
"description": "explicit assigns named Topic refs; auto classifies omitted Topics; mixed keeps explicit rows and classifies the rest. Default auto."
},
"topicRefs": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "Topic refs from topicDefinitions to assign to a single search."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"idempotencyKey": {
"type": "string",
"minLength": 1
},
"next_refresh_at": {
"type": "string",
"minLength": 1
},
"topicDefinitions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Existing or inline-create Topic definitions with stable refs. Several searches may share one new Topic ref."
},
"allowCreateTopics": {
"type": "boolean",
"description": "When topicMode is auto or mixed, whether automatic organisation may propose new Topics. Default true."
},
"refresh_frequency": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}| topicMode | string | explicit assigns named Topic refs; auto classifies omitted Topics; mixed keeps explicit rows and classifies the rest. Default auto. |
| topicRefs | array | Topic refs from topicDefinitions to assign to a single search. |
| workspaceId* | string | Authorized workspace for this requested write; discover accessible context first. |
| idempotencyKey | string |
| next_refresh_at | string |
| topicDefinitions | array | Existing or inline-create Topic definitions with stable refs. Several searches may share one new Topic ref. |
| allowCreateTopics | boolean | When topicMode is auto or mixed, whether automatic organisation may propose new Topics. Default true. |
| refresh_frequency | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"platform",
"type",
"value"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"keyword",
"hashtag"
],
"type": "string"
},
"items": {
"type": "array",
"items": {},
"description": "Batch searches. Each item may include value, region, platform, and topicRefs."
},
"value": {
"type": "string",
"minLength": 1
},
"region": {
"type": "string",
"minLength": 1
},
"command": {
"type": "object",
"description": "Canonical preview command snapshot. Send this on execute so automatic assignments are not reclassified.",
"additionalProperties": {}
},
"brandIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"platform": {
"type": "string",
"minLength": 1,
"description": "Supported tracking platform key, such as instagram, tiktok or youtube; the backend rejects unsupported platforms."
},
"topicMode": {
"enum": [
"explicit",
"auto",
"mixed"
],
"type": "string",
"description": "explicit assigns named Topic refs; auto classifies omitted Topics; mixed keeps explicit rows and classifies the rest. Default auto."
},
"topicRefs": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "Topic refs from topicDefinitions to assign to a single search."
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"idempotencyKey": {
"type": "string",
"minLength": 1
},
"next_refresh_at": {
"type": "string",
"minLength": 1
},
"topicDefinitions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Existing or inline-create Topic definitions with stable refs. Several searches may share one new Topic ref."
},
"allowCreateTopics": {
"type": "boolean",
"description": "When topicMode is auto or mixed, whether automatic organisation may propose new Topics. Default true."
},
"refresh_frequency": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"workspaceId",
"edits"
],
"properties": {
"edits": {
"type": "object",
"properties": {
"cta": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"goal": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 20000
},
{
"type": "null"
}
]
},
"hooks": {
"type": [
"array",
"null"
],
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 2000
},
"maxItems": 20
},
{
"type": "null"
}
]
},
"title": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
]
},
"concept": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 20000
},
{
"type": "null"
}
]
},
"hashtags": {
"type": [
"array",
"null"
],
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 30
},
{
"type": "null"
}
]
},
"heroShot": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 20000
},
{
"type": "null"
}
]
},
"shotList": {
"type": [
"array",
"null"
],
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"required": [
"step",
"beat"
],
"properties": {
"beat": {
"type": "string",
"maxLength": 2000,
"minLength": 1
},
"step": {
"type": "integer",
"exclusiveMinimum": 0
},
"overlay": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 60
},
{
"type": "null"
}
]
},
"description": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 20000
},
{
"type": "null"
}
]
},
"keyDirectives": {
"type": [
"array",
"null"
],
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 2000
},
"maxItems": 30
},
{
"type": "null"
}
]
},
"targetSeoKeywords": {
"type": [
"array",
"null"
],
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"maxItems": 30
},
{
"type": "null"
}
]
},
"whyThisBriefExists": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"maxLength": 20000
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"editId": {
"type": "string",
"maxLength": 100
},
"brandId": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"briefId": {
"type": "string",
"format": "uuid"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Authorized workspace for this requested write; discover accessible context first."
},
"opportunityKey": {
"type": "string",
"maxLength": 128,
"minLength": 8
},
"strategyRevisionId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "revisionId of a brand Strategy already returned in this conversation (strategyContext.revisionId). When it is still current, the Strategy is not repeated."
}
},
"additionalProperties": false
}