{ "openapi": "3.0.3", "info": { "title": "Vista Social API", "version": "2.0.0", "description": "Public REST API for Vista Social. Each endpoint maps to a platform capability. Authenticate with your API key. This specification is generated automatically from the live capability catalog, so it always reflects what the platform can do.\n\n**Connecting an AI agent or assistant?** Vista Social also offers a dedicated **MCP (Model Context Protocol) server** that exposes these same capabilities to MCP-compatible clients such as Claude, ChatGPT, and Cursor. **If your goal is to connect to an AI agent, MCP is usually the best route** — the agent discovers and calls these tools directly, without you writing REST integration code. Find your MCP connection details in your account under [Settings → Integrations](https://vistasocial.com/settings/preferences/integrations).", "x-catalog-version": "2026-04-21" }, "servers": [ { "url": "https://api.vistasocial.com", "description": "Production" } ], "security": [ { "ApiKeyHeader": [] } ], "tags": [ { "name": "Publishing & scheduling", "description": "Create, schedule, and manage posts, drafts, ideas, media, and publishing queues across your connected social profiles." }, { "name": "Shared calendars", "description": "Create and manage public share links so clients and reviewers can view a filtered slice of your publishing calendar." }, { "name": "Reports & analytics", "description": "Retrieve performance metrics, benchmarks, and reporting data for your profiles and published posts." }, { "name": "Trends & social listening", "description": "Discover trending content and monitor keywords with trend listeners." }, { "name": "Inbox & community management", "description": "Review and respond to messages, comments, and reviews from your social inbox." }, { "name": "Tasks & workflows", "description": "Run your team's work: project boards, tasks, assignees, due dates, checklists, attachments, comments, and custom fields." }, { "name": "Accounts, profiles & teams", "description": "Look up connected social profiles, profile groups, and teammates." }, { "name": "Vista Pages (link-in-bio)", "description": "Manage Vista Page (link-in-bio) sites and their content." }, { "name": "Utilities", "description": "General-purpose utilities and helpers." }, { "name": "automation" } ], "paths": { "/v2/posts/comments/add": { "post": { "operationId": "postsCommentsAdd", "summary": "Add internal comment", "description": "Leaves an internal collaboration comment on a post or inbox item.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "addInternalComment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addInternalCommentRequest" }, "example": { "message": "Summer sale starts now!", "post_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/attachments/add": { "post": { "operationId": "tasksAttachmentsAdd", "summary": "Attach a file or link to a Vista Work task", "description": "Attaches a file or link to a Vista Work task.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "addTaskAttachment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addTaskAttachmentRequest" }, "example": { "task_id": "64f0aa11bb22cc33dd44ee55", "url": "https://example.com/brief.pdf", "name": "Launch brief" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "attachments": [ { "id": "64bb11bb22cc33dd44ee5701", "type": "link", "url": "https://example.com/brief.pdf", "name": "Launch brief" } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/checklist/add": { "post": { "operationId": "tasksChecklistAdd", "summary": "Add a Vista Work checklist item", "description": "Adds a checklist item on a Vista Work task.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "addTaskChecklistItem", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addTaskChecklistItemRequest" }, "example": { "task_id": "64f0aa11bb22cc33dd44ee55", "title": "Outline talking points", "assignee_user_id": "me" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "checklist": [ { "id": "64aa11bb22cc33dd44ee5601", "title": "Outline", "done": true, "assignee": 42, "due_date": null, "order": 0 }, { "id": "64aa11bb22cc33dd44ee5602", "title": "Outline talking points", "done": false, "assignee": 42, "due_date": null, "order": 1 } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/comments/add": { "post": { "operationId": "tasksCommentsAdd", "summary": "Comment on a Vista Work task", "description": "Adds a comment to a Vista Work task, with optional @mentions.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "addTaskComment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addTaskCommentRequest" }, "example": { "task_id": "64f0aa11bb22cc33dd44ee55", "message": "Draft is ready for review, @[Jane Doe](8)." } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "comments": [ { "id": "64ee11bb22cc33dd44ee5902", "user_gid": 42, "message": "Draft is ready for review, @[Jane Doe](8).", "mentions": [ 8 ], "created": "2026-06-28T13:00:00.000Z" } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/macros/apply": { "post": { "operationId": "macrosApply", "summary": "Apply a macro to inbox items", "description": "Applies a saved inbox macro to a conversation or inbox item.", "tags": [ "Inbox & community management" ], "x-vista-tool": "applyMacro", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/applyMacroRequest" }, "example": { "macro_id": "64a1b2c3d4e5f6a7b8c9d0e1", "inbox_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "ok": true, "macro_id": "674c1b2c3d4e5f6789012345", "macro_name": "Mark VIP + complete", "macro_type": "message", "inbox_count": 1, "target_results": [ { "inbox_id": "674a1b2c3d4e5f6789012345", "conversation_id": "674a1b2c3d4e5f6789012346", "ok": true, "executed": [ { "action": "apply_labels", "result": { "success": true } } ], "errors": [] } ], "executed": [ { "action": "apply_labels", "result": { "success": true }, "inbox_id": "674a1b2c3d4e5f6789012345", "conversation_id": "674a1b2c3d4e5f6789012346" } ], "unsupported": [], "errors": [] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/posts/review": { "post": { "operationId": "postsReview", "summary": "Approve or reject post(s)", "description": "Approves or rejects a post that's waiting in an approval workflow.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "approveOrRejectPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/approveOrRejectPostRequest" }, "example": { "publication_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ], "reject": false, "reviewer_notes": "Follow up with the customer." } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/approveOrRejectPostResponse" }, "example": { "ok": true, "data": { "action": "approve", "publication_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ], "publication_group_ids": [ "64f0aa11bb22cc33dd44ee55" ], "reviewer_notes": "Looks good, approved for scheduling.", "result": { "success": [ { "publication_group_id": "64f0aa11bb22cc33dd44ee55" } ], "errors": [] } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/calendar/notes/create": { "post": { "operationId": "calendarNotesCreate", "summary": "Create a calendar note", "description": "Adds a note or event marker on your content calendar for a specific date.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "createCalendarNote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createCalendarNoteRequest" }, "example": { "title": "Product launch", "note": "example", "date": "2026-06-28T14:00:00-04:00", "visibility": "Public", "color": "Alice Blue", "profile_group_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": { "_id": "64a1b2c3d4e5f6a7b8c9d0e1", "root_entity_gid": "entity_AcMe123", "user_gid": 42, "entities": [ "entity_AcMe123" ], "title": "Product launch", "date": "2026-06-28T00:00:00.000Z", "description": "Launch day reminder for the team.", "color": "linear-gradient(135deg, rgb(121, 40, 202), rgb(255, 0, 128))", "isPrivate": true, "created_at": "2026-06-28T12:00:00.000Z", "updated_at": "2026-06-28T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/macros/create": { "post": { "operationId": "macrosCreate", "summary": "Create a message macro", "description": "Creates a new inbox macro (canned reply or workflow action).", "tags": [ "Inbox & community management" ], "x-vista-tool": "createMacro", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createMacroRequest" }, "example": { "name": "Jane Doe", "profile_group_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ], "actions": [ { "type": "labels", "labels": [ "summer-campaign" ] } ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": "674c1b2c3d4e5f6789012345", "data": { "id": "674c1b2c3d4e5f6789012345", "value": "674c1b2c3d4e5f6789012345", "label": "Mark VIP + complete", "name": "Mark VIP + complete", "type": "message", "description": "", "entities": [ { "name": "Acme Brand", "id": "entity_AcMe123", "label": "Acme Brand", "value": "entity_AcMe123" } ], "actions": [ { "type": "apply_labels", "data": { "labels": [ { "label": "VIP" } ] } }, { "type": "star", "data": {} } ] } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/media/create": { "post": { "operationId": "mediaCreate", "summary": "Create media", "description": "Uploads media (image, video, GIF) into your Vista Social media library, with optional video thumbnail_url or thumb_offset.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "createMedia", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createMediaRequest" }, "example": { "type": "image", "media_url": [ "https://cdn.vistasocial.com/m/hero.jpg" ], "name": "hero.jpg" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ], "requested": 1, "created": 1, "failed": 0, "failures": [], "parent_gid": "64abcabcabcabcabcabcabca" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/automations/save": { "post": { "operationId": "automationsSave", "summary": "Create or update a DM automation", "description": "Creates or updates a DM automation that auto-replies to comments, DMs, story replies, mentions, or reviews.", "tags": [ "automation" ], "x-vista-tool": "createOrUpdateAutomation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createOrUpdateAutomationRequest" }, "example": { "profile_id": 12345, "name": "Giveaway comment-to-DM", "save_type": "save_and_set_live", "triggers": [ { "type": "comment", "target_type": "specific", "target_id": [ { "id": "18033445566778899" } ], "keywords": [ "link", "info" ], "match_whole_word": false, "enabled": true } ], "actions": [ { "action": "comment", "variants": [ { "type": "text", "text": "Thanks! Sending you a DM now." } ] }, { "action": "dm", "variants": [ { "type": "card", "title": "Here is your link", "subtitle": "Tap below to grab the guide", "buttons": [ { "title": "Get the guide", "url": "https://example.com/guide" } ] } ] } ], "once_per_user": true } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/ideas/save": { "post": { "operationId": "ideasSave", "summary": "Create or update idea", "description": "Saves a new post idea to your idea board or updates an existing one.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "createOrUpdateIdea", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createOrUpdateIdeaRequest" }, "example": { "message": "Summer sale starts now!", "media_url": [ "https://cdn.vistasocial.com/m/hero.jpg" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/posts/save": { "post": { "operationId": "postsSave", "summary": "Create or update a post", "description": "Drafts, schedules, or edits a social post across one or more connected profiles.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "createOrUpdatePost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createOrUpdatePostRequest" }, "example": { "profile_id": 12345, "message": "Summer sale starts now!" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": [ "64a1b2c3d4e5f6a7b8c9d0e1" ], "draft": false } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/projects/save": { "post": { "operationId": "projectsSave", "summary": "Create or update a Vista Work project", "description": "Creates a Vista Work project (task board) or updates an existing one.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "createOrUpdateProject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createOrUpdateProjectRequest" }, "example": { "profile_group_id": "entity_AcMe123", "name": "Summer Campaign", "color": "#2E7CF6" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "project": { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "entity_gid": "entity_AcMe123", "name": "Summer Campaign", "description": "Launch tasks for the summer push.", "color": "#7928CA", "icon": "rocket", "is_default": false, "archived": null, "statuses": [ { "key": "not_started", "name": "Not started", "category": "not_started", "order": 0 }, { "key": "in_progress", "name": "In progress", "category": "active", "order": 1 }, { "key": "completed", "name": "Completed", "category": "closed", "order": 2 } ], "members": [] } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/shared-calendars/save": { "post": { "operationId": "sharedCalendarsSave", "summary": "Create or update a shared calendar link", "description": "Creates or edits a public share link so clients and reviewers can view a filtered slice of your publishing calendar.", "tags": [ "Shared calendars" ], "x-vista-tool": "createOrUpdateSharedCalendar", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createOrUpdateSharedCalendarRequest" }, "example": { "title": "Product launch", "profile_ids": [ 12345 ], "from_date": "2026-06-01", "timezone": "America/New_York" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/create": { "post": { "operationId": "tasksCreate", "summary": "Create or update a Vista Work task", "description": "Creates a Vista Work task or updates an existing one, including status, assignees, and due date.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "createOrUpdateTask", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createOrUpdateTaskRequest" }, "example": { "profile_group_id": "entity_AcMe123", "title": "Draft launch announcement", "description": "Write the announcement copy and route it for review.", "priority": "high", "assignee_user_ids": [ "me" ], "due_date": "2026-06-30", "custom_fields": [ { "field": "Budget", "value": "2500" }, { "field": "Campaign", "value": "Summer" } ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "task": { "id": "64f0aa11bb22cc33dd44ee55", "project_gid": "64a1b2c3d4e5f6a7b8c9d0e1", "entity_gid": "entity_AcMe123", "title": "Draft launch announcement", "description": "Write the announcement copy and route it for review.", "status_key": "todo", "priority": "high", "assignees": [ 42 ], "watchers": [], "labels": [ "copy" ], "custom_fields": [ { "field_id": "64bb22cc33dd44ee55ff6601", "value": 2500, "name": "Budget", "type": "number" } ], "start_date": null, "due_date": "2026-06-30", "due_has_time": false, "order": 1, "is_completed": false, "completed_at": null, "completed_by": null, "parent_task_gid": null, "subtasks_total": 0, "subtasks_done": 0, "subtasks": [], "attachments": [], "links": [], "comments_count": 0, "created": "2026-06-28T10:00:00.000Z", "updated": "2026-06-28T10:00:00.000Z" } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/users/save": { "post": { "operationId": "usersSave", "summary": "Create or update user", "description": "Invites a new teammate or updates an existing teammate's profile-group access and permissions.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "createOrUpdateUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createOrUpdateUserRequest" }, "example": { "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "access": "MANAGER" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createOrUpdateUserResponse" }, "example": { "ok": true, "data": { "id": 42 } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/profile-groups/create": { "post": { "operationId": "profileGroupsCreate", "summary": "Create profile group", "description": "Creates a new profile group to organize connected profiles.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "createProfileGroup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createProfileGroupRequest" }, "example": { "name": "Jane Doe", "type": "AGENCY", "country": "example", "timezone": "America/New_York" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": "entity_NewClient", "name": "New Client Group", "connect_link": "https://app.vistasocial.com/connect/entity_NewClient" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/trend-listeners/create": { "post": { "operationId": "trendListenersCreate", "summary": "Create a persistent trends listener", "description": "Creates a persistent trend listener that monitors a topic, brand, or vertical across the trend pipeline and saves matches you can review later.", "tags": [ "Trends & social listening" ], "x-vista-tool": "createTrendListener", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTrendListenerRequest" }, "example": { "name": "Jane Doe", "sources": [ "x_news_trend" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "data": { "listener": { "_id": "674abc123def456789012345", "name": "Brand watch", "description": "", "enabled": true, "status": "active", "sources": [ { "kind": "x_news_trend", "external": { "regions": [ "US", "GB" ] } } ], "keyword_count": 2, "processed": null, "results": 0, "created": "2026-06-28T12:00:00.000Z" } } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/posts/delete": { "post": { "operationId": "postsDelete", "summary": "Delete post(s)", "description": "Delete one or more posts by `publication_id`. Pass a single id or an array of ids. Works for drafts, scheduled posts, and published posts: a published post is also removed from the social network on networks that support deletion, while a draft or scheduled post is cancelled so it never publishes. Deletion is permanent and cannot be undone. The caller must have authored the post or hold manage access to the target profile. Optionally include a `reason` that is stored in the post history and shared in deletion notifications.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "deletePost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deletePostRequest" }, "example": { "publication_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deletePostResponse" }, "example": { "ok": true, "data": { "deleted": [ "64a1b2c3d4e5f6a7b8c9d0e1" ], "problems": [] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/shared-calendars/delete": { "post": { "operationId": "sharedCalendarsDelete", "summary": "Delete shared calendar links", "description": "Revokes a shared calendar link so its public URL stops working.", "tags": [ "Shared calendars" ], "x-vista-tool": "deleteSharedCalendar", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteSharedCalendarRequest" }, "example": { "shared_calendar_id": "64a1b2c3d4e5f6a7b8c9d0e1", "shared_calendar_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/delete": { "post": { "operationId": "tasksDelete", "summary": "Delete a Vista Work task", "description": "Deletes a Vista Work task and its subtasks.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "deleteTask", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteTaskRequest" }, "example": { "task_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "success": true, "deleted_ids": [ "64f0aa11bb22cc33dd44ee55" ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/checklist/delete": { "post": { "operationId": "tasksChecklistDelete", "summary": "Delete a Vista Work checklist item", "description": "Deletes a checklist item from a Vista Work task.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "deleteTaskChecklistItem", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteTaskChecklistItemRequest" }, "example": { "task_id": "64f0aa11bb22cc33dd44ee55", "checklist_item_id": "64aa11bb22cc33dd44ee5601" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "checklist": [ { "id": "64aa11bb22cc33dd44ee5602", "title": "Outline talking points", "done": true, "assignee": 42, "due_date": null, "order": 0 } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/comments/delete": { "post": { "operationId": "tasksCommentsDelete", "summary": "Delete a Vista Work task comment", "description": "Deletes a comment from a Vista Work task.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "deleteTaskComment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteTaskCommentRequest" }, "example": { "task_id": "64f0aa11bb22cc33dd44ee55", "comment_id": "64ee11bb22cc33dd44ee5902" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "success": true, "comments": [] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/users/delete": { "post": { "operationId": "usersDelete", "summary": "Delete user", "description": "Removes a teammate from one or more profile groups, or offboards them entirely.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "deleteUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteUserRequest" }, "example": { "user_id": 12345, "profile_group_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteUserResponse" }, "example": { "ok": true, "data": {} } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/projects/duplicate": { "post": { "operationId": "projectsDuplicate", "summary": "Duplicate a Vista Work project", "description": "Duplicates a Vista Work project and its tasks in the same profile group.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "duplicateProject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/duplicateProjectRequest" }, "example": { "project_id": "64a1b2c3d4e5f6a7b8c9d0e1", "name": "Summer Campaign (Demo)" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "project": { "id": "64a1b2c3d4e5f6a7b8c9d0e2", "entity_gid": "entity_AcMe123", "name": "Summer Campaign (Demo)", "description": "Launch tasks for the summer push.", "color": "#7928CA", "icon": "rocket", "is_default": false, "archived": null, "statuses": [ { "key": "not_started", "name": "Not started", "category": "not_started", "order": 0 }, { "key": "in_progress", "name": "In progress", "category": "active", "order": 1 }, { "key": "completed", "name": "Completed", "category": "closed", "order": 2 } ], "members": [] } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/media/search": { "post": { "operationId": "mediaSearch", "summary": "Find media (library or external)", "description": "Searches your media library and stock libraries (Unsplash, Pexels, GIFs) for images or videos to use in posts.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "findMedia", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/findMediaRequest" }, "example": { "path": "library", "labels": [ "summer-campaign" ], "q": "summer campaign" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "folders": [ { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "title": "Campaign assets" } ], "path": [ "64a1b2c3d4e5f6a7b8c9d0e1" ], "current_folder_id": "64a1b2c3d4e5f6a7b8c9d0e1", "data": [ { "media_gid": "64f0aa11bb22cc33dd44ee55", "title": "hero.jpg", "type": "image", "url": "https://cdn.vistasocial.com/m/hero.jpg", "thumbnail_url": "https://cdn.vistasocial.com/m/hero_thumb.jpg", "created": "2026-06-01T10:00:00.000Z", "description": "Product hero shot", "labels": [ "summer-campaign" ] } ], "medias_count": [ { "total": 42 } ], "hasNextPage": true } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/profile-groups/list": { "post": { "operationId": "profileGroupsList", "summary": "Find profile groups", "description": "Lists or searches profile groups in your workspace.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "findProfileGroups", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/findProfileGroupsRequest" }, "example": { "profile_group_name": "example", "profile_group_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/findProfileGroupsResponse" }, "example": { "ok": true, "data": [ { "profile_group_id": "entity_AcMe123", "name": "Acme Brand", "type": "brand", "timezone": "America/New_York" } ] } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/profiles/search": { "post": { "operationId": "profilesSearch", "summary": "Find profiles", "description": "Finds social profiles connected to your workspace by name, network, or profile group.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "findProfiles", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/findProfilesRequest" }, "example": { "profile_id": 12345, "q": "summer campaign" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/findProfilesResponse" }, "example": { "ok": true, "data": [ { "id": 12345, "name": "Acme Brand (Facebook Page)", "status": "ok" }, { "id": 12346, "name": "Acme Brand (Instagram)", "status": "ok", "network": "Instagram Business", "network_code": "instagram" } ] } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/trends/search": { "post": { "operationId": "trendsSearch", "summary": "Find what is trending right now", "description": "Returns the top trending topics and stories aggregated across X (Twitter) Trends, X News, YouTube most-popular, and Google Trends, deduplicated and ranked.", "tags": [ "Trends & social listening" ], "x-vista-tool": "findTrendingNow", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/findTrendingNowRequest" }, "example": { "limit": 10 } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "data": { "trends": [ { "id": "us:ai-regulation", "name": "ai regulation", "display_name": "AI Regulation", "type": "topic", "region": "US", "vertical": "technology", "platforms": [ "x_news", "google" ], "signals": { "x_news": { "story_id": "123456", "category": "Technology", "cluster_post_count": 42, "summary": "Lawmakers debate new AI rules.", "hook": "What it means for businesses", "recency_hours": 2.5 }, "google": { "interest": 78, "rising": true, "breakout": false } }, "composite_score": 72.4, "source_count": 2, "first_seen": "2026-06-28T10:00:00.000Z" } ], "meta": { "region": "US", "vertical": null, "sources_responding": [ "x_news", "google" ], "sources_partial": [], "generated_at": "2026-06-28T12:00:00.000Z", "from_cache": true, "cache_age_seconds": 120, "stale": false } } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/automations/get": { "post": { "operationId": "automationsGet", "summary": "Get a DM automation", "description": "Gets a single DM automation's full configuration (triggers, actions, schedule).", "tags": [ "automation" ], "x-vista-tool": "getAutomation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getAutomationRequest" }, "example": { "automation_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "automation": { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "profile_id": 12345, "name": "Giveaway comment-to-DM", "active": true, "triggers": [ { "id": "64a1b2c3d4e5f6a7b8c9d0f2", "type": "comment", "target_type": "specific", "target_id": [ { "id": "18033445566778899" } ], "keywords": [ "link", "info" ], "exclude_keywords": [ "scam" ], "match_whole_word": false, "enabled": true, "chats": 128 } ], "actions": [ { "action": "comment", "variants": [ { "type": "text", "text": "Thanks! Sending you a DM now." } ] }, { "action": "dm", "variants": [ { "type": "card", "title": "Here is your link", "subtitle": "Tap below to grab the guide", "buttons": [ { "title": "Get the guide", "url": "https://example.com/guide" } ] } ] } ], "days_of_week": [ 1, 2, 3, 4, 5 ], "hours_from": 9, "hours_to": 17, "timezone": "America/New_York", "sequence": 0, "exclusive": true, "once_per_user": true, "insights": { "chats": 128, "clicks": 74, "dms_sent": 128, "comments_sent": 128, "contacts": 119 }, "created_at": "2026-06-28T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/automations/results": { "post": { "operationId": "automationsResults", "summary": "Get DM automation results", "description": "Reads a DM automation's performance: runs, DMs and comments sent, clicks, contacts, and a daily timeline.", "tags": [ "automation" ], "x-vista-tool": "getAutomationResults", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getAutomationResultsRequest" }, "example": { "automation_id": "64a1b2c3d4e5f6a7b8c9d0e1", "dateFrom": "2026-06-01", "dateTo": "2026-06-30", "include": [ "summary", "timeline", "contacts" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "automation_id": "64a1b2c3d4e5f6a7b8c9d0e1", "name": "Giveaway comment-to-DM", "summary": { "chats": 128, "clicks": 74, "dms_sent": 128, "comments_sent": 128, "contacts": 119 }, "timeline": { "name": "Automation performance", "dates": { "dateFrom": "2026-06-01", "dateTo": "2026-06-30", "priorFrom": "2026-05-02", "priorTo": "2026-05-31" }, "reports": [ { "key": "chats", "content": [ { "type": "chart", "chartType": "bar", "data": { "values": [ { "name": "Actions", "data": [ [ 1748736000000, 12 ], [ 1748822400000, 9 ] ] } ] } } ] } ], "users": [ { "user_gid": "17841400000000000", "name": "Jane Doe", "username": "janedoe", "count": 3 } ] }, "contacts": [ { "user_gid": "17841400000000000", "name": "Jane Doe", "username": "janedoe", "count": 3 } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/devices/list": { "post": { "operationId": "devicesList", "summary": "Get publishing devices", "description": "Lists mobile devices registered to your workspace for publishing with the Vista Social app.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "getDevices", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getDevicesRequest" }, "example": { "profile_group_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "devices_by_entity": { "entity_AcMe123": [ { "device_gid": "device-uuid-1", "name": "Jane's iPhone" }, { "device_gid": "device-uuid-2", "name": "Front desk iPad" } ] } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/reports/inbox-performance": { "post": { "operationId": "reportsInboxPerformance", "summary": "Get inbox response performance report", "description": "Reports on inbox response time, action rate, and community management performance over a period.", "tags": [ "Inbox & community management" ], "x-vista-tool": "getInboxResponsePerformanceReport", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getInboxResponsePerformanceReportRequest" }, "example": { "profile_id": [ 12345 ], "dateFrom": "2026-06-01T00:00:00.000Z", "dateTo": "2026-06-30T23:59:59.000Z" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "reports": { "name": "Inbox performance report", "tabs": [ { "code": "cross_channel", "display": "Cross channel" } ], "crossChannel": { "code": "cross_channel", "display": "Cross channel", "summary": [ { "key": "received_messages", "value": 320, "display": "320", "growth": 12.5, "title": "Received messages" }, { "key": "actioned_messages", "value": 280, "display": "280", "growth": 8.1, "title": "Actioned messages" }, { "key": "average_response", "value": 4.2, "display": "4.2 minutes", "growth": -15, "title": "Average response" } ], "report": [ { "key": "chats", "title": "Received and actioned messages", "content": [ { "type": "chart", "chartType": "line", "data": { "values": [ { "name": "Received messages", "data": [ 10, 12 ] } ] } } ] } ] } }, "dates": { "dateFrom": "2026-06-01", "dateTo": "2026-06-28", "priorFrom": "2026-05-01", "priorTo": "2026-05-31" }, "timezone": "America/New_York" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/inbox/stats": { "post": { "operationId": "inboxStats", "summary": "Get inbox stats (counts and breakdowns)", "description": "Counts inbox items (messages, comments, reviews, mentions) grouped by type, profile, or status.", "tags": [ "Inbox & community management" ], "x-vista-tool": "getInboxStats", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getInboxStatsRequest" }, "example": { "profile_id": [ 12345 ], "labels": [ "summer-campaign" ], "q": "summer campaign" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "total": 142, "breakdown": [ { "key": "comment", "count": 87 }, { "key": "message", "count": 55 } ], "group_by": "type", "filters": { "profile_id": [ 12345 ], "types": [], "sentiment": [], "labels": [], "seen": true, "own": false, "received_after": "2026-05-29T00:00:00.000Z", "received_before": "2026-06-28T23:59:59.999Z" } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/reports/industry-benchmark": { "post": { "operationId": "reportsIndustryBenchmark", "summary": "Get industry benchmark report", "description": "Compares your profile's posting cadence, engagement, and growth to industry peers with percentile rankings.", "tags": [ "Reports & analytics" ], "x-vista-tool": "getIndustryBenchmark", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getIndustryBenchmarkRequest" }, "example": { "profile_id": [ 12345 ], "dateFrom": "2026-06-01T00:00:00.000Z", "dateTo": "2026-06-30T23:59:59.000Z" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "name": "Industry benchmark", "summary": [], "reports": [ { "key": "profile_performance_and_comparison", "title": "Retail", "subTitle": "Profile performance and comparison to other brands within the same industry.", "contentDirection": "column", "content": [ { "key": "followers", "title": "Followers", "type": "chart", "chartType": "bar", "data": { "values": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 5432 ], "label": { "title": { "defaultMessage": "You are in the 60th percentile." }, "bg_color": "#27AE60" } } } ] } ], "dates": { "dateFrom": "2026-06-01", "dateTo": "2026-06-28", "priorFrom": "2026-05-01", "priorTo": "2026-05-31" }, "timezone": "America/New_York", "extraText": "", "hideIndicators": false } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/posts/optimal-times": { "post": { "operationId": "postsOptimalTimes", "summary": "Get optimal publishing times", "description": "Suggests the best times to publish to a profile based on historical audience activity.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "getOptimalPublishTimes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getOptimalPublishTimesRequest" }, "example": { "profile_id": [ 12345 ], "timezone": "America/New_York" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "12345": { "timezone": "America/New_York", "posts": 87, "times": [ { "hour": 9, "minute": 30, "value": 18 }, { "hour": 14, "minute": 15, "value": 12 } ] } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/posts/get": { "post": { "operationId": "postsGet", "summary": "Get post by id", "description": "Retrieves the full details of a specific post by id.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "getPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getPostRequest" }, "example": { "post_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": [ { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "status": "APPROVED", "status_label": "Scheduled", "author": { "name": "Jane Doe", "email": "jane@example.com" }, "message": "Summer sale starts now! 🌞", "publish_at": "2026-06-28T14:00:00-04:00", "timezone": "America/New_York", "profile": { "name": "Acme Co", "username": "acmeco", "network": "Facebook Page", "profile_url": "https://facebook.com/acmeco", "picture_url": "https://cdn.vistasocial.com/p/12345.jpg" }, "medias": [ { "type": "image", "url": "https://cdn.vistasocial.com/m/hero.jpg" } ], "labels": [ "summer-campaign" ], "internal_link": "https://vistasocial.com/calendar?id=64a1b2c3d4e5f6a7b8c9d0e1" } ] } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/reports/profile-metrics": { "post": { "operationId": "reportsProfileMetrics", "summary": "Get daily profile metrics", "description": "Returns daily follower, reach, impression, and engagement totals for a profile or profile group across a date range.", "tags": [ "Reports & analytics" ], "x-vista-tool": "getProfileMetrics", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getProfileMetricsRequest" }, "example": { "profile_ids": [ 12345 ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "meta": { "response_mode": "compact", "latest_only": false, "row_count": 2, "profile_count": 1, "network_count": 1, "date_from": "2026-06-01", "date_to": "2026-06-02" }, "columns": [ "profile_gid", "date", "network", "impressions", "followers" ], "rows": [ [ 12345, "20260601", "instagram", 1200, 5432 ], [ 12345, "20260602", "instagram", 980, 5440 ] ], "summary": { "numeric_totals": { "impressions": 2180, "followers": 10872 } } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/queues/list": { "post": { "operationId": "queuesList", "summary": "Get publishing queues", "description": "Lists scheduling queues and their time slots for a profile.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "getProfileQueues", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getProfileQueuesRequest" }, "example": { "profile_id": 12345 } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "queues": [ { "queue_id": "64a1b2c3d4e5f6a7b8c9d0e1", "root_entity_gid": "entity_AcMe123", "entity_gid": "entity_AcMe123", "profile_id": 12345, "timezone": "America/New_York", "evergreen": false, "labels": [ "summer-campaign" ], "schedule": [ { "day": 1, "slots": [ { "hour": 9, "minute": 0, "labels": [ "summer-campaign" ] } ] } ], "next": { "queue_next": "2026-06-29T13:00:00.000Z", "queue_available": "2026-06-29T13:00:00.000Z", "queue_last": "2026-07-06T13:00:00.000Z" } } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/reports/post-performance": { "post": { "operationId": "reportsPostPerformance", "summary": "Get published post performance", "description": "Ranks published posts by impressions, engagement, or other metrics to surface your top performers.", "tags": [ "Reports & analytics" ], "x-vista-tool": "getPublishedPostPerformance", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getPublishedPostPerformanceRequest" }, "example": { "date_from": "2026-06-01T00:00:00.000Z", "date_to": "2026-06-30T23:59:59.000Z", "profile_ids": [ 12345 ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "meta": { "source": "integration/data export_type=post", "date_from": "2026-06-01", "date_to": "2026-06-28", "metric": "impressions", "secondary_metric": "engagement", "sort_order": "desc", "candidates_count": 47, "returned_count": 1 }, "columns": [ "rank", "primary_metric", "primary_value", "secondary_metric", "secondary_value", "id", "date", "time", "timezone", "source", "message", "published_link", "profile_gid", "network", "type", "impressions", "engagement" ], "rows": [ [ 1, "impressions", 12000, "engagement", 340, "64a1b2c3d4e5f6a7b8c9d0e1", "June 1, 2026", "9:00 AM", "America/New_York", "VISTA SOCIAL", "Summer launch is live!", "https://facebook.com/acmeco/posts/123", 12345, "instagram", "Image", 12000, 340 ] ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/reports/sentiment": { "post": { "operationId": "reportsSentiment", "summary": "Get sentiment analysis report", "description": "Reports on positive, neutral, and negative sentiment across inbox interactions.", "tags": [ "Inbox & community management" ], "x-vista-tool": "getSentimentReport", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getSentimentReportRequest" }, "example": { "profile_id": [ 12345 ], "dateFrom": "2026-06-01T00:00:00.000Z", "dateTo": "2026-06-30T23:59:59.000Z" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "name": "Sentiment analysis", "summary": [ { "key": "positive_sentiment", "title": "Positive", "display": "42%", "growth": 5.2 }, { "key": "negative_sentiment", "title": "Negative", "display": "18%", "growth": -1.1 }, { "key": "neutral_sentiment", "title": "Neutral", "display": "35%", "growth": 0 } ], "reports": [ { "key": "awareness", "title": "Overall sentiment", "contentDirection": "row", "content": [ { "type": "chart", "chartType": "donut", "data": { "values": [ { "name": "Positive", "y": 42, "color": "#0063E3" } ] } } ] } ], "dates": { "dateFrom": "2026-06-01", "dateTo": "2026-06-28", "priorFrom": "2026-05-01", "priorTo": "2026-05-31" }, "timezone": "America/New_York", "extraText": "", "hideIndicators": false } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/get": { "post": { "operationId": "tasksGet", "summary": "Get a Vista Work task", "description": "Gets one Vista Work task in full, including its custom fields, subtasks, comments, and activity.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "getTask", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getTaskRequest" }, "example": { "task_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "task": { "id": "64f0aa11bb22cc33dd44ee55", "project_gid": "64a1b2c3d4e5f6a7b8c9d0e1", "entity_gid": "entity_AcMe123", "title": "Draft launch announcement", "description": "Write the announcement copy and route it for review.", "status_key": "in_progress", "priority": "high", "assignees": [ 42 ], "watchers": [ 8 ], "labels": [ "copy" ], "custom_fields": [ { "field_id": "64bb22cc33dd44ee55ff6601", "value": 2500, "name": "Budget", "type": "number" }, { "field_id": "64bb22cc33dd44ee55ff6602", "value": "summer", "name": "Campaign", "type": "dropdown", "label": "Summer" } ], "start_date": null, "due_date": "2026-06-30", "due_has_time": false, "order": 1, "is_completed": false, "completed_at": null, "completed_by": null, "parent_task_gid": null, "subtasks_total": 2, "subtasks_done": 1, "subtasks": [ { "id": "64aa11bb22cc33dd44ee5601", "title": "Outline", "done": true, "assignee": 42, "due_date": null, "order": 0 }, { "id": "64aa11bb22cc33dd44ee5602", "title": "First draft", "done": false, "assignee": 42, "due_date": "2026-06-29", "order": 1 } ], "attachments": [], "links": [ { "type": "publication", "ref_id": "64cc11bb22cc33dd44ee5701", "group_id": "64dd11bb22cc33dd44ee5801" } ], "comments_count": 2, "created": "2026-06-18T09:12:00.000Z", "updated": "2026-06-28T12:05:00.000Z" }, "project": { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "name": "Summer Campaign", "statuses": [ { "key": "not_started", "name": "Not started", "category": "not_started", "order": 0 }, { "key": "in_progress", "name": "In progress", "category": "active", "order": 1 }, { "key": "completed", "name": "Completed", "category": "closed", "order": 2 } ], "timezone": "America/New_York" }, "parent": null, "child_tasks": [ { "id": "64f0aa11bb22cc33dd44ee77", "project_gid": "64a1b2c3d4e5f6a7b8c9d0e1", "entity_gid": "entity_AcMe123", "title": "Write the subject line", "status_key": "todo", "priority": "none", "assignees": [ 42 ], "due_date": null, "due_has_time": false, "is_completed": false, "subtasks_total": 0, "subtasks_done": 0, "comments_count": 0, "parent_task_gid": "64f0aa11bb22cc33dd44ee55", "labels": [], "created": "2026-06-20T14:00:00.000Z", "updated": "2026-06-20T14:00:00.000Z" } ], "custom_field_definitions": [ { "id": "64bb22cc33dd44ee55ff6601", "name": "Budget", "type": "number", "required": false, "profile_group_id": "entity_AcMe123", "project_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ] } ], "comments": [ { "id": "64ee11bb22cc33dd44ee5901", "user_gid": 8, "message": "Let's highlight the discount code.", "mentions": [], "created": "2026-06-28T12:00:00.000Z" } ], "activity": [ { "action": "status_changed", "meta": { "from": "todo", "to": "in_progress" }, "user_gid": 42, "created": "2026-06-28T11:00:00.000Z" } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/trend-listeners/matches": { "post": { "operationId": "trendListenersMatches", "summary": "Read captured trend matches for a listener", "description": "Returns the trends a specific listener has caught, with first-seen / last-seen timestamps, match counts, and source attribution.", "tags": [ "Trends & social listening" ], "x-vista-tool": "getTrendListenerMatches", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getTrendListenerMatchesRequest" }, "example": { "listener_gid": "64a1b2c3d4e5f6a7b8c9d0e1", "limit": 10 } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "data": { "listener": { "_id": "674abc123def456789012345", "name": "Brand watch", "enabled": true, "status": "active", "sources": [ { "kind": "x_news_trend", "external": {} } ], "keyword_count": 2, "processed": "2026-06-28T08:00:00.000Z", "results": 12, "created": "2026-06-01T00:00:00.000Z", "description": "" }, "matches": [ { "_id": "674def456abc789012345678", "trend_id": "us:ai-regulation", "display_name": "AI Regulation", "type": "topic", "region": "US", "vertical": "technology", "platforms": [ "x_news" ], "matched_sources": [ "x_news" ], "source_count": 1, "composite_score": 68.2, "first_seen": "2026-06-20T00:00:00.000Z", "last_seen": "2026-06-28T00:00:00.000Z", "match_count": 3 } ] }, "meta": { "from_date": "2026-05-29T12:00:00.000Z", "to_date": "2026-06-28T12:00:00.000Z", "count": 1 } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/users/get": { "post": { "operationId": "usersGet", "summary": "Get user", "description": "Gets a single team member's profile groups, roles, and permissions.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "getUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getUserRequest" }, "example": { "user_id": 12345, "email": "jane@example.com" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": 7, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "last_active": "2026-06-28T14:00:00.000Z", "invited": "Jun 1", "joined": "2025", "online_status": "online", "profile_group_count": 2, "labels": [ "editors" ], "profile_groups": [ { "id": "entity_AcMe123", "name": "Acme Retail", "role": "ADMIN" }, { "id": "entity_Store99", "name": "Downtown Store", "role": "RESTRICTED", "permissions": { "publish": "CONTRIBUTOR", "reports": "VIEW", "inbox": "MANAGE", "reviews": "NONE" }, "labels": [ "editors" ] } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/pages/list": { "post": { "operationId": "pagesList", "summary": "List Vista Pages", "description": "Lists your Vista Pages (link-in-bio landing pages).", "tags": [ "Vista Pages (link-in-bio)" ], "x-vista-tool": "getVistaPages", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getVistaPagesRequest" }, "example": {} } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": [ { "_id": "64a1b2c3d4e5f6a7b8c9d0e1", "name": "Acme Link in Bio", "slug": "acme-link-in-bio", "picture_url": "https://cdn.vistasocial.com/vp/acme.jpg", "entity_gid": "entity_AcMe123", "root_entity_gid": "entity_AcMe123", "profile_gid": 12345, "domain": "acme.vista.page", "published": true, "has_unpublished_changes": false, "created_at": "2026-06-01T10:00:00.000Z", "updated_at": "2026-06-28T12:00:00.000Z" } ] } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/pages/import": { "post": { "operationId": "pagesImport", "summary": "Import Vista Page", "description": "Imports an existing link-in-bio page (Linktree, Buffer Start Page, Bitly, etc.) into Vista Social, or generates a starter page with AI.", "tags": [ "Vista Pages (link-in-bio)" ], "x-vista-tool": "importVistaPage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/importVistaPageRequest" }, "example": { "type": "ai", "profile_group_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/inbox/actions": { "post": { "operationId": "inboxActions", "summary": "Perform an action on an inbox item or conversation", "description": "Labels, stars, completes, reports spam, replies to, or adjusts sentiment on inbox messages, comments, and reviews.", "tags": [ "Inbox & community management" ], "x-vista-tool": "inboxAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inboxActionRequest" }, "example": { "action": "star", "message": "Summer sale starts now!", "labels": [ "summer-campaign" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "success": true } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/automations/search": { "post": { "operationId": "automationsSearch", "summary": "List DM automations", "description": "Lists DM automations with summary stats (runs, DMs, comments, clicks, contacts).", "tags": [ "automation" ], "x-vista-tool": "listAutomations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listAutomationsRequest" }, "example": { "profile_ids": [ 12345 ], "status": "active", "q": "giveaway", "page": 0 } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "automations": [ { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "name": "Giveaway comment-to-DM", "profile_id": 12345, "network": "instagram", "profile_name": "@acme", "active": true, "standby": false, "triggers": [ { "type": "comment", "target_type": "specific", "keywords": [ "link", "info" ] } ], "actions": [ { "action": "comment", "type": "text" }, { "action": "dm", "type": "card" } ], "insights": { "chats": 128, "clicks": 74, "dms_sent": 128, "contacts": 119 }, "created_at": "2026-06-28T12:00:00.000Z" } ], "summary": [ { "key": "active", "value": 3 }, { "key": "paused", "value": 1 } ], "hasNextPage": false, "page": 0 } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/boosts/list": { "post": { "operationId": "boostsList", "summary": "List boost configurations for a profile", "description": "Lists paid-promotion (boost) configurations available for a profile.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "listBoostConfigurations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listBoostConfigurationsRequest" }, "example": { "profile_id": 12345 } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "data": [ { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "name": "Default boost", "created": "Jun 01, 2026", "publications_counter": 12, "used": "2026-06-15T10:00:00.000Z", "profile": { "id": 12345, "name": "Acme Co", "network": { "code": "facebook", "display": "Facebook Page" }, "picture_url": "https://cdn.vistasocial.com/p/12345.jpg" }, "configuration": { "budget": 50, "objective": "ENGAGEMENT" } } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/calendars/list": { "post": { "operationId": "calendarsList", "summary": "List external calendars", "description": "Lists external calendars (Google Calendar, ICS feeds) linked to your Vista Social content calendar.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "listExternalCalendars", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listExternalCalendarsRequest" }, "example": {} } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "external_calendars": [ { "url": "https://calendar.google.com/calendar/ical/example/basic.ics", "color": "#4A6B96" } ], "show_external_calendars": true } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/ideas/search": { "post": { "operationId": "ideasSearch", "summary": "List ideas", "description": "Browses saved post ideas and filters them by label, folder, or id.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "listIdeas", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listIdeasRequest" }, "example": { "path": "/", "labels": [ "summer-campaign" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "folders": [ { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "title": "Campaign ideas" } ], "ideas": [ { "id": "64f0aa11bb22cc33dd44ee55", "message": "Behind-the-scenes reel for the summer launch.", "attachments": [ { "type": "image", "thumbnail_url": "https://cdn.vistasocial.com/m/thumb.jpg" } ], "users": [ { "id": "42", "name": "Jane Doe" } ], "since": "3 days ago" } ], "has_next_page": false, "page": 0, "path": [ "64a1b2c3d4e5f6a7b8c9d0e1" ], "current_folder_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/inbox/search": { "post": { "operationId": "inboxSearch", "summary": "List inbox items (comments, messages, mentions, reviews, shares, IG collab invites).", "description": "Browses inbox messages, comments, reviews, or mentions with filters for sender, label, sentiment, or status.", "tags": [ "Inbox & community management" ], "x-vista-tool": "listInboxItems", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listInboxItemsRequest" }, "example": { "profile_id": [ 12345 ], "labels": [ "summer-campaign" ], "q": "summer campaign" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "items": [ { "inbox_id": "674a1b2c3d4e5f6789012345", "conversation_id": "674a1b2c3d4e5f6789012346", "url": "https://facebook.com/acmeco/posts/123", "vista_url": "https://app.vistasocial.com/inbox/674a1b2c3d4e5f6789012346", "network": "facebook", "message": "Thanks for reaching out — do you ship internationally?", "message_truncated": false, "type": "comment", "sentiment": "positive", "user": { "name": "Jane Doe", "username": "janedoe" }, "received": "2026-06-28T14:30:00.000Z", "profile_id": 12345, "starred": true, "labels": [ "VIP" ] } ], "total": 156, "limit": 20, "skip": 0, "returned": 1, "has_more": true, "full_text": false, "include_parent": false } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/macros/list": { "post": { "operationId": "macrosList", "summary": "List available macros", "description": "Lists saved inbox macros (canned actions and replies).", "tags": [ "Inbox & community management" ], "x-vista-tool": "listMacros", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listMacrosRequest" }, "example": { "type": "image" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "data": [ { "id": "674c1b2c3d4e5f6789012345", "value": "674c1b2c3d4e5f6789012345", "label": "Mark VIP + complete", "name": "Mark VIP + complete", "type": "message", "description": "Apply the VIP label and mark the conversation done.", "entities": [ { "name": "Acme Brand", "id": "entity_AcMe123", "label": "Acme Brand", "value": "entity_AcMe123" } ], "actions": [ { "type": "apply_labels", "data": { "labels": [ { "label": "VIP", "value": "VIP" } ] } }, { "type": "mark_complete", "data": {} } ] } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/my": { "post": { "operationId": "tasksMy", "summary": "List my Vista Work tasks", "description": "Lists the tasks assigned to you across all Vista Work projects, grouped by due date.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "listMyTasks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listMyTasksRequest" }, "example": { "timezone": "America/New_York" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "groups": { "overdue": [ { "id": "64f0aa11bb22cc33dd44ee55", "project_gid": "64a1b2c3d4e5f6a7b8c9d0e1", "entity_gid": "entity_AcMe123", "title": "Draft launch announcement", "status_key": "in_progress", "priority": "high", "assignees": [ 42 ], "due_date": "2026-06-27", "due_has_time": false, "is_completed": false, "subtasks_total": 3, "subtasks_done": 1, "comments_count": 2, "parent_task_gid": null, "labels": [ "copy" ], "created": "2026-06-18T09:12:00.000Z", "updated": "2026-06-24T16:40:00.000Z", "project_name": "Summer Campaign" } ], "today": [], "upcoming": [ { "id": "64f0aa11bb22cc33dd44ee66", "project_gid": "64a1b2c3d4e5f6a7b8c9d0e1", "entity_gid": "entity_AcMe123", "title": "Schedule teaser posts", "status_key": "todo", "priority": "normal", "assignees": [ 42 ], "due_date": "2026-07-02", "due_has_time": false, "is_completed": false, "subtasks_total": 0, "subtasks_done": 0, "comments_count": 0, "parent_task_gid": null, "labels": [], "project_name": "Summer Campaign" } ], "no_due": [] }, "total": 2 } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/networks/list": { "post": { "operationId": "networksList", "summary": "Get available networks", "description": "Lists social networks supported by Vista Social.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "listNetworks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listNetworksRequest" }, "example": {} } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listNetworksResponse" }, "example": { "ok": true, "data": { "networks": [ { "name": "Facebook Page", "id": 1, "code": "facebook", "display": "Facebook Page", "type": "page", "daily_posts": 25 }, { "name": "Instagram Business", "id": 2, "code": "instagram", "display": "Instagram Business", "type": "business", "daily_posts": 25 } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/posts/comments/list": { "post": { "operationId": "postsCommentsList", "summary": "Get post comments", "description": "Lists comments and replies on a published post.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "listPostComments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listPostCommentsRequest" }, "example": { "post_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": [ { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "link": "https://vistasocial.com/calendar?id=64f0aa11bb22cc33dd44ee55", "message": "Can we push the CTA higher in the caption?", "created_at": "2026-06-28T12:00:00.000Z", "user": { "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "picture": "https://cdn.vistasocial.com/u/42.jpg" } } ] } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/posts/search": { "post": { "operationId": "postsSearch", "summary": "Search posts (calendar)", "description": "Retrieve posts from your publishing calendar. Select posts either by filters — one or more `status` values plus `profile_ids`, optionally narrowed by a `dateFrom`/`dateTo` range — or look up specific posts directly with `publication_ids`. Each row includes the post id, type, status, publish time, text, attached media, labels, author, and (when `include_insights` is true) performance metrics for published posts. Use `limit` to cap results, and `include_media_urls` / `include_full_message` to control payload size.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "listPosts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listPostsRequest" }, "example": { "profile_ids": [ 12345 ], "labels": [ "summer-campaign" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "meta": { "response_mode": "compact", "grouped": false, "row_count": 2, "matched_count": 2, "counts_scope": "filtered", "date_from": "2026-05-29", "date_to": "2026-06-28" }, "columns": [ "id", "publication_group_id", "type", "profile_id", "profile_name", "network", "status", "status_label", "review_meta", "author_id", "author_name", "author_type", "publish_at", "timezone", "timezone_abbr", "publish_at_formatted", "published_via", "message", "message_truncated", "published_link", "internal_link", "media_counts" ], "rows": [ [ "64a1b2c3d4e5f6a7b8c9d0e1", "64f0aa11bb22cc33dd44ee60", "IMAGE", 12345, "Acme Co", "Facebook Page", "SCHEDULED", "Scheduled", null, 42, "Jane Doe", "user", "2026-06-28T14:00:00-04:00", "America/New_York", "EDT", "Jun 28, 2026 at 2:00 PM EDT", "vista social", "Summer sale starts now!", false, null, "https://vistasocial.com/calendar?id=64a1b2c3d4e5f6a7b8c9d0e1", { "images": 1, "videos": 0, "documents": 0 } ], [ "64a1b2c3d4e5f6a7b8c9d0f2", "64f0aa11bb22cc33dd44ee61", "REEL", 12346, "Acme Co", "Instagram Business", "PUBLISHED", "Published", null, 42, "Jane Doe", "user", "2026-06-20T09:30:00-04:00", "America/New_York", "EDT", "Jun 20, 2026 at 9:30 AM EDT", "vista social", "Behind the scenes of our summer shoot", false, "https://www.instagram.com/reel/Cxyz123/", "https://vistasocial.com/calendar?id=64a1b2c3d4e5f6a7b8c9d0f2", { "images": 0, "videos": 1, "documents": 0 } ] ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/projects/list": { "post": { "operationId": "projectsList", "summary": "List Vista Work projects", "description": "Lists your Vista Work projects (task boards) with each project's statuses and members.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "listProjects", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listProjectsRequest" }, "example": { "profile_group_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ], "archived": true } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "projects": [ { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "entity_gid": "entity_AcMe123", "name": "Summer Campaign", "description": "Launch tasks for the summer push.", "color": "#7928CA", "icon": "rocket", "is_default": false, "archived": null, "statuses": [ { "key": "not_started", "name": "Not started", "category": "not_started", "order": 0 }, { "key": "in_progress", "name": "In progress", "category": "active", "order": 1 }, { "key": "completed", "name": "Completed", "category": "closed", "order": 2 } ], "members": [ { "user_gid": 42, "name": "Alex Owner", "role": "MANAGE" }, { "user_gid": 8, "name": "Jane Doe", "role": "VIEW" } ] } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/shared-calendars/list": { "post": { "operationId": "sharedCalendarsList", "summary": "List shared calendar links", "description": "Lists the public share links people use to view a filtered slice of your Vista Social publishing calendar.", "tags": [ "Shared calendars" ], "x-vista-tool": "listSharedCalendars", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listSharedCalendarsRequest" }, "example": { "profile_ids": [ 12345 ], "status": "active" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "data": [ { "id": "674d1b2c3d4e5f6789012345", "title": "Acme Q3 content review", "link": "https://app.vistasocial.com/shared-calendar/9fKq2Lm4", "profiles": [ { "id": 12345, "name": "Acme Brand (Facebook Page)", "network": "facebook" } ], "from_date": "2026-07-01", "to_date": "2026-09-30", "timezone": "America/New_York", "auto_delete": false, "can_comment": true, "show_external_posts": true, "show_review_posts": false, "statuses": [ "scheduled", "published" ], "labels": [ "Campaign" ], "authors": [ { "id": 28, "name": "Jane Doe" } ], "recipient_emails": [ "client@acme.example" ], "updated": "2026-06-28T14:30:00.000Z", "created": "2026-06-01T09:00:00.000Z" } ], "total": 3, "limit": 20, "offset": 0 } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/task-fields/list": { "post": { "operationId": "taskFieldsList", "summary": "List Vista Work custom fields and labels", "description": "Lists the custom fields that apply to Vista Work tasks, plus your Work labels.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "listTaskFields", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listTaskFieldsRequest" }, "example": { "project_id": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "custom_fields": [ { "id": "64bb22cc33dd44ee55ff6601", "name": "Budget", "type": "number", "required": false, "profile_group_id": "entity_AcMe123", "project_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ] }, { "id": "64bb22cc33dd44ee55ff6602", "name": "Campaign", "type": "dropdown", "required": true, "profile_group_id": "entity_AcMe123", "options": [ { "key": "summer", "label": "Summer" }, { "key": "holiday", "label": "Holiday" } ], "project_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ] } ], "labels": [ "copy", "design", "urgent" ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/search": { "post": { "operationId": "tasksSearch", "summary": "List or search Vista Work tasks", "description": "Lists tasks in a Vista Work project, or searches tasks by title across projects.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "listTasks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listTasksRequest" }, "example": { "q": "launch announcement", "profile_group_ids": [ "entity_AcMe123" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "tasks": [ { "id": "64f0aa11bb22cc33dd44ee55", "project_gid": "64a1b2c3d4e5f6a7b8c9d0e1", "entity_gid": "entity_AcMe123", "title": "Draft launch announcement", "status_key": "in_progress", "priority": "high", "assignees": [ 42 ], "due_date": "2026-06-30", "due_has_time": false, "is_completed": false, "subtasks_total": 3, "subtasks_done": 1, "comments_count": 2, "parent_task_gid": null, "labels": [ "copy" ], "created": "2026-06-18T09:12:00.000Z", "updated": "2026-06-24T16:40:00.000Z", "project_name": "Summer Campaign", "link_count": 1 } ], "mode": "search" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/timezones/list": { "post": { "operationId": "timezonesList", "summary": "Finds available timezones", "description": "Lists IANA timezones (internal helper).", "tags": [ "Utilities" ], "x-vista-tool": "listTimezones", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listTimezonesRequest" }, "example": {} } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": [ { "id": "America/Los_Angeles", "name": "(GMT -07:00) America/Los Angeles" }, { "id": "America/New_York", "name": "(GMT -04:00) America/New York" } ] } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/trend-listeners/list": { "post": { "operationId": "trendListenersList", "summary": "List trend listeners for the active entity", "description": "Lists all your active and paused trend listeners with their configuration and most recent match counts.", "tags": [ "Trends & social listening" ], "x-vista-tool": "listTrendListeners", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listTrendListenersRequest" }, "example": { "enabled_only": true } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "data": { "listeners": [ { "_id": "674abc123def456789012345", "name": "AI trends", "description": "", "enabled": true, "status": "active", "sources": [ { "kind": "x_news_trend", "external": { "regions": [ "US" ] } } ], "keyword_count": 3, "processed": "2026-06-28T08:00:00.000Z", "results": 12, "created": "2026-06-01T00:00:00.000Z" } ] } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/users/list": { "post": { "operationId": "usersList", "summary": "List users", "description": "Lists teammates in your Vista Social workspace.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "listUsers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listUsersRequest" }, "example": { "q": "summer campaign", "status": "all" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "total": 106, "count": 2, "columns": [ "id", "first", "last", "email", "last_active", "invited", "joined", "status", "groups", "labels" ], "rows": [ [ 7, "Jane", "Doe", "jane@example.com", "2026-06-28T14:00:00.000Z", "Jun 1", "2025", "online", 2, [ "editors" ] ], [ 8, "John", "Smith", "john@example.com", "2026-06-27T09:30:00.000Z", "Jun 3", null, "offline", 1, [] ] ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/workflows/list": { "post": { "operationId": "workflowsList", "summary": "Get workflows", "description": "Lists approval workflows available for your profile groups.", "tags": [ "Inbox & community management" ], "x-vista-tool": "listWorkflows", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listWorkflowsRequest" }, "example": { "profile_group_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": [ { "id": "674abc123def456789012345", "name": "Content review" }, { "id": "674def456abc789012345678", "name": "Legal approval" } ] } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/calendars/manage": { "post": { "operationId": "calendarsManage", "summary": "Manage external calendar", "description": "Connects or removes external calendar feeds (Google Calendar, ICS) so their events appear in your content calendar.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "manageExternalCalendar", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/manageExternalCalendarRequest" }, "example": { "action": "add", "url": "https://cdn.vistasocial.com/m/hero.jpg" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "action": "add", "changed": true, "external_calendars": [ { "url": "https://calendar.google.com/calendar/ical/example/basic.ics", "color": "#FF5733" } ], "show_external_calendars": true } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/projects/statuses": { "post": { "operationId": "projectsStatuses", "summary": "Manage Vista Work project statuses", "description": "Customizes the status columns on a Vista Work project board.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "manageProjectStatuses", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/manageProjectStatusesRequest" }, "example": { "project_id": "64a1b2c3d4e5f6a7b8c9d0e1", "statuses": [ { "key": "backlog", "name": "Backlog", "category": "not_started", "order": 0, "color": "#8C9AAA" }, { "key": "in_progress", "name": "In progress", "category": "active", "order": 1, "color": "#2E7CF6" }, { "key": "in_review", "name": "In review", "category": "active", "order": 2, "color": "#F5A623" }, { "key": "done", "name": "Done", "category": "done", "order": 3, "color": "#27AE60" } ] } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "project": { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "entity_gid": "entity_AcMe123", "name": "Summer Campaign", "description": "Launch tasks for the summer push.", "color": "#7928CA", "icon": "rocket", "is_default": false, "archived": null, "statuses": [ { "key": "backlog", "name": "Backlog", "category": "not_started", "order": 0 }, { "key": "in_progress", "name": "In progress", "category": "active", "order": 1 }, { "key": "in_review", "name": "In review", "category": "active", "order": 2 }, { "key": "done", "name": "Done", "category": "done", "order": 3 } ], "members": [] }, "status_changes": { "completed": 0, "reopened": 0, "migrated": 0 } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/attachments/remove": { "post": { "operationId": "tasksAttachmentsRemove", "summary": "Remove a Vista Work task attachment", "description": "Removes an attachment from a Vista Work task.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "removeTaskAttachment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/removeTaskAttachmentRequest" }, "example": { "task_id": "64f0aa11bb22cc33dd44ee55", "attachment_id": "64bb11bb22cc33dd44ee5701" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "attachments": [] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/profile-groups/search": { "post": { "operationId": "profileGroupsSearch", "summary": "Finds profile group by name", "description": "Searches profile groups by name (internal helper; the `POST /v2/profile-groups/list` endpoint is the preferred entry point).", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "searchProfileGroups", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/searchProfileGroupsRequest" }, "example": { "profile_group_name": "example" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/searchProfileGroupsResponse" }, "example": { "ok": true, "data": [ { "id": "entity_AcMe123", "name": "Acme Brand", "type": "brand", "timezone": "America/New_York", "connect_url": "https://app.vistasocial.com/connect/entity_AcMe123" } ] } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/automations/status": { "post": { "operationId": "automationsStatus", "summary": "Activate, pause, or delete DM automations", "description": "Activates, pauses, or deletes one or more DM automations.", "tags": [ "automation" ], "x-vista-tool": "setAutomationStatus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/setAutomationStatusRequest" }, "example": { "automation_ids": [ "64a1b2c3d4e5f6a7b8c9d0e1" ], "status": "paused" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "automations": [ { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "active": true } ], "permission_required": false } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/media/update": { "post": { "operationId": "mediaUpdate", "summary": "Update media", "description": "Updates an existing media library item's title, description, alt text, labels, or video thumbnail.", "tags": [ "Publishing & scheduling" ], "x-vista-tool": "updateMedia", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateMediaRequest" }, "example": { "media_id": "64a1b2c3d4e5f6a7b8c9d0e1", "labels": [ "summer-campaign" ], "title": "Product launch" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "id": "64a1b2c3d4e5f6a7b8c9d0e1", "data": { "media_gid": "64a1b2c3d4e5f6a7b8c9d0e1", "id": "64a1b2c3d4e5f6a7b8c9d0e1", "type": "image", "title": "hero.jpg", "description": "Updated product hero shot", "alt_text": "Product on a white background", "labels": [ "summer-campaign", "hero" ], "url": "https://cdn.vistasocial.com/m/hero.jpg", "thumbnail_url": "https://cdn.vistasocial.com/m/hero_thumb.jpg", "width": 1200, "height": 800, "size": 245760, "mime": "image/jpeg", "extension": "jpg" } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/profile-groups/update": { "post": { "operationId": "profileGroupsUpdate", "summary": "Update profile group settings", "description": "Updates a profile group's settings: name, timezone, brand voice (max 2,000 characters), limits (max users/profiles, disabled networks), publishing controls, and AI features.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "updateProfileGroup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateProfileGroupRequest" }, "example": { "profile_group_id": "64a1b2c3d4e5f6a7b8c9d0e1", "name": "Jane Doe", "timezone": "America/New_York" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "success": true, "profile_group_id": "entity_AcMe123" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/checklist/update": { "post": { "operationId": "tasksChecklistUpdate", "summary": "Update a Vista Work checklist item", "description": "Updates or completes a checklist item on a Vista Work task.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "updateTaskChecklistItem", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateTaskChecklistItemRequest" }, "example": { "task_id": "64f0aa11bb22cc33dd44ee55", "checklist_item_id": "64aa11bb22cc33dd44ee5601", "done": true } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "checklist": [ { "id": "64aa11bb22cc33dd44ee5601", "title": "Outline", "done": true, "assignee": 42, "due_date": null, "order": 0 }, { "id": "64aa11bb22cc33dd44ee5602", "title": "Outline talking points", "done": true, "assignee": 42, "due_date": null, "order": 1 } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/tasks/comments/update": { "post": { "operationId": "tasksCommentsUpdate", "summary": "Edit a Vista Work task comment", "description": "Edits the text of your own comment on a Vista Work task.", "tags": [ "Tasks & workflows" ], "x-vista-tool": "updateTaskComment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateTaskCommentRequest" }, "example": { "task_id": "64f0aa11bb22cc33dd44ee55", "comment_id": "64ee11bb22cc33dd44ee5902", "message": "Draft is ready for review, @[Jane Doe](8). Deadline moved to Friday." } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "comments": [ { "id": "64ee11bb22cc33dd44ee5902", "user_gid": 42, "message": "Draft is ready for review, @[Jane Doe](8). Deadline moved to Friday.", "mentions": [ 8 ], "created": "2026-06-28T13:00:00.000Z" } ] } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/trend-listeners/update": { "post": { "operationId": "trendListenersUpdate", "summary": "Update a trend listener", "description": "Updates an existing trend listener — change keywords, regions, sources, pause/resume, or delete.", "tags": [ "Trends & social listening" ], "x-vista-tool": "updateTrendListener", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateTrendListenerRequest" }, "example": { "listener_gid": "64a1b2c3d4e5f6a7b8c9d0e1" } } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSuccessResponse" }, "example": { "ok": true, "data": { "data": { "listener": { "_id": "674abc123def456789012345", "name": "Brand watch", "description": "", "enabled": false, "status": "archived", "sources": [ { "kind": "x_news_trend", "external": {} } ], "keyword_count": 4, "processed": null, "results": 0, "created": "2026-06-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } }, "/v2/me": { "post": { "operationId": "me", "summary": "Get current user identity", "description": "Returns the name and email of the user whose API key is in use, so callers can confirm they are connected to the expected Vista Social account before performing actions.", "tags": [ "Accounts, profiles & teams" ], "x-vista-tool": "whoami", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/whoamiRequest" }, "example": {} } } }, "responses": { "200": { "description": "Tool executed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/whoamiResponse" }, "example": { "ok": true, "data": { "name": "Jane Doe", "email": "jane@example.com" } } } } }, "400": { "description": "Invalid request — the JSON body failed input validation (a required field is missing or a value has the wrong type). `error.code` is `invalid_request` (or a tool-specific business error code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "invalid_request", "message": "profile_ids: Required" } } } } }, "401": { "description": "Missing or invalid API key (or an expired/invalid OAuth token). `error.code` is `unauthorized`. Authenticate with the `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } } } }, "403": { "description": "Authenticated, but the workspace plan does not permit this call (API access / integration / subscription gating). `error.code` is `forbidden`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "forbidden", "message": "Your subscription does not offer API access." } } } } }, "429": { "description": "Rate limit exceeded for this integration. Honor the `Retry-After` and `X-RateLimit-*` response headers before retrying. `error.code` is `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "rate_limited", "message": "You are going too fast, please slow down." } } } } }, "500": { "description": "Unexpected server error. `error.code` is `internal_error`; the message is generic (internal details are never exposed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "internal_error", "message": "Unable to process the request." } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your Vista Social API key, sent in the `x-api-key` header. The `api_key` query parameter is also accepted." } }, "schemas": { "ToolSuccessResponse": { "type": "object", "description": "Standard envelope returned by every tool endpoint on success.", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true for a 2xx response." }, "data": { "description": "Tool-specific result payload. The exact shape depends on the tool; see each operation for examples as they are documented.", "nullable": true } }, "required": [ "ok", "data" ] }, "ErrorResponse": { "type": "object", "description": "Standard error envelope returned on every non-2xx response. `error.message` is human-readable; `error.code` is a stable machine-readable string you can branch on.", "properties": { "ok": { "type": "boolean", "enum": [ false ], "description": "Always false for an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code. Common values: `invalid_request` (400), `unauthorized` (401 — missing/invalid API key or token), `forbidden` (403 — plan/subscription gating), `not_found` (404), `method_not_allowed` (405), `rate_limited` (429), `internal_error` (500), `service_unavailable` (503). Some 400s carry a tool-specific business error code instead." }, "message": { "type": "string", "description": "Human-readable error message, safe to surface to end users." } }, "required": [ "message" ] } }, "required": [ "ok", "error" ], "example": { "ok": false, "error": { "code": "unauthorized", "message": "Invalid API key" } } }, "addInternalCommentRequest": { "type": "object", "properties": { "message": { "type": "string", "description": "\n Internal team comment text. This field is required.\n If you don't have more information, you can ask the user about it and wait until you have the information.\n " }, "post_id": { "type": "string", "description": "Target id for the internal comment: a publication id (the `POST /v2/posts/save` endpoint/the `POST /v2/posts/search` endpoint), a native post id (the `POST /v2/posts/search` endpoint), or an inbox item id (the `POST /v2/inbox/search` endpoint)." }, "post_type": { "type": "string", "enum": [ "PUBLICATION", "MESSAGE" ], "description": "Whether post_id is a Vista Social publication (scheduled/drafted in Vista) or a message (natively published post with author_type='external', or an inbox item). Defaults to PUBLICATION." }, "internal": { "type": "boolean", "description": "Optional visibility flag. Defaults to true. Keep true for team-only comments." } }, "required": [ "message", "post_id" ], "additionalProperties": false }, "addTaskAttachmentRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The Vista Work task id to attach to (from the `POST /v2/tasks/search` endpoint or the `POST /v2/tasks/get` endpoint)." }, "media_gid": { "type": "string", "description": "Media library id to attach (from the `POST /v2/media/search` endpoint or the `POST /v2/media/create` endpoint). Prefer this when the file is already in Vista Social." }, "url": { "type": "string", "description": "Public http(s) URL to attach when media_gid is not used." }, "name": { "type": "string", "description": "Optional display name for the attachment." } }, "required": [ "task_id" ], "additionalProperties": false }, "addTaskChecklistItemRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The Vista Work task id that owns the checklist (from the `POST /v2/tasks/search` endpoint or the `POST /v2/tasks/get` endpoint)." }, "title": { "type": "string", "description": "Checklist item title." }, "assignee_user_id": { "type": "string", "description": "Optional assignee for this checklist row. Each entry is a user_gid (from the `POST /v2/users/list` endpoint or a project's members), an email, a full name, or \"me\" (the caller). Resolved against the project group: a name/email that matches nobody is rejected, and a user_gid that is not a member of that group is SKIPPED while the call still succeeds (the response says which ids were skipped). So resolve people with the `POST /v2/users/list` endpoint profile_group_id= rather than from the whole account roster." }, "due_date": { "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2})?)?$", "description": "Optional due date for this checklist row. Format as YYYY-MM-DD, or YYYY-MM-DD HH:MM for a specific time." } }, "required": [ "task_id", "title" ], "additionalProperties": false }, "addTaskCommentRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The Vista Work task id to comment on (from the `POST /v2/tasks/search` endpoint or the `POST /v2/tasks/get` endpoint)." }, "message": { "type": "string", "description": "Comment text. Supports @[Name](user_gid) mentions." } }, "required": [ "task_id", "message" ], "additionalProperties": false }, "applyMacroRequest": { "type": "object", "properties": { "macro_id": { "type": "string", "description": "Macro ID. Use the `POST /v2/macros/list` endpoint to discover available macros." }, "inbox_id": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ], "description": "Inbox message ID from the `POST /v2/inbox/search` endpoint, or an array of IDs for batch apply." }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ], "description": "Conversation ID from the `POST /v2/inbox/search` endpoint; may be a single value or index-aligned array for batch apply." } }, "required": [ "macro_id", "inbox_id" ], "additionalProperties": false }, "approveOrRejectPostRequest": { "type": "object", "properties": { "publication_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "One or more publication ids to approve/reject. Use the `POST /v2/posts/search` endpoint to find ids when the user references posts by text/date." }, "reject": { "type": "boolean", "description": "Decision flag: false = approve, true = reject." }, "reviewer_notes": { "type": "string", "description": "Optional reviewer notes to include with the decision." } }, "required": [ "publication_ids", "reject" ], "additionalProperties": false }, "approveOrRejectPostResponse": { "type": "object", "description": "Standard envelope returned by this endpoint on success.", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true for a 2xx response." }, "data": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approve", "reject" ], "description": "Decision that was applied." }, "publication_ids": { "type": "array", "items": { "type": "string" }, "description": "Publication ids from the request." }, "publication_group_ids": { "type": "array", "items": { "type": "string" }, "description": "Review groups those publications belong to." }, "reviewer_notes": { "type": "string", "nullable": true, "description": "Notes sent with the decision. Null when none were provided." }, "result": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "object", "properties": { "publication_group_id": { "type": "string" } }, "additionalProperties": true }, "description": "Review groups that were approved or rejected." }, "errors": { "type": "array", "items": {}, "description": "Per-group failures. Empty on a full success." } }, "additionalProperties": true, "description": "Upstream approve/reject outcome." } }, "required": [ "action", "publication_ids", "publication_group_ids", "reviewer_notes", "result" ], "additionalProperties": false } }, "required": [ "ok", "data" ] }, "createCalendarNoteRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "\n Title of the note. This is field is required. \n If you don't have more information, you can ask the user about it and wait until you have the information.\n " }, "note": { "type": "string", "description": "\n Note message. This is field is required. \n If you don't have more information, you can ask the user about it and wait until you have the information.\n " }, "date": { "type": "string", "description": "\n Note date. Date must be in the future. \n Provide date user enters in ISO 8601 format. \n This field is required.\n If you don't have more information, you can ask the user about it and wait until you have the information.\n " }, "visibility": { "type": "string", "enum": [ "Public", "Private" ], "description": "User can specify if note should be public or private. Public notes will be visible to all users. Private notes will be visible only to the user. By default all notes are public." }, "color": { "type": "string", "enum": [ "Alice Blue", "Blue Violet", "Bright Gold", "Cornflower Blue", "Cotton Candy Pink", "Ghost White", "Golden Yellow", "Lavender Blush", "Lavender", "Light Apricot", "Light Blue", "Light Cyan", "Light Gold", "Light Golden Yellow", "Light Gray", "Light Green", "Light Grey", "Light Lime", "Light Peach", "Light Periwinkle", "Light Purple", "Light Salmon", "Light Sky Blue", "Mint Green", "Orchid", "Peach Puff", "Peach", "Periwinkle", "Salmon Pink", "Sky Blue", "Turquoise", "Watermelon" ], "description": "User can specify the color of the note" }, "profile_group_ids": { "type": "array", "items": { "type": "string" }, "description": "\n List of profile group that this note will be associated with. Use profile_group_id from the `POST /v2/profile-groups/list` endpoint or the `POST /v2/profile-groups/search` endpoint tools. At least profile group must be provided.\n " } }, "required": [ "title", "note", "date", "visibility", "color", "profile_group_ids" ], "additionalProperties": false }, "createMacroRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Macro name." }, "description": { "type": "string", "description": "Optional macro description." }, "profile_group_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "One or more profile group IDs where this macro should be available." }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "labels", "mark_complete", "mark_read", "star" ], "description": "Action type. One of: labels, mark_complete, mark_read, star." }, "labels": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Label names to apply. Required only when type is \"labels\"; omit it for mark_complete, mark_read, and star." } }, "required": [ "type" ], "additionalProperties": false }, "minItems": 1, "description": "List of macro actions to run. Each action is an object with a \"type\" and, only for the labels action, a \"labels\" array. Examples: {\"type\":\"labels\",\"labels\":[\"urgent\"]}, {\"type\":\"mark_complete\"}, {\"type\":\"mark_read\"}, {\"type\":\"star\"}. Only the \"labels\" action takes a labels array; omit labels for the others." } }, "required": [ "name", "profile_group_ids", "actions" ], "additionalProperties": false }, "createMediaRequest": { "type": "object", "properties": { "profile_group_ids": { "type": "array", "items": { "type": "string" }, "description": "Optional list of profile group ids that this media (file or folder) will be associated with, for example [\"101\",\"102\"]. Use profile_group_id from the `POST /v2/profile-groups/list` endpoint or the `POST /v2/profile-groups/search` endpoint. Omit to make the media available to all profile groups." }, "media_url": { "type": "array", "items": { "type": "string" }, "description": "FILE uploads only (type image/video/document): links to an image, video, or document. Required for a file upload; omit entirely when type is \"folder\". Verify that links are valid and accessible. Offer to help the user find media if they do not have it." }, "type": { "type": "string", "enum": [ "image", "video", "document", "folder" ], "description": "What to create: \"image\", \"video\" or \"document\" to upload a file, or \"folder\" to create a library folder. Required." }, "name": { "type": "string", "description": "For a FOLDER (type \"folder\") this is the folder title and is REQUIRED. For a FILE upload it is the optional media name — if a file name is available, use it." }, "parent_gid": { "type": "string", "description": "The destination folder for this media (works for BOTH a file upload and a new folder): the 24-char hex \"id\" of an existing folder from a the `POST /v2/media/search` endpoint folders[] entry. Omit to use the library root. Never guess an id and never pass a folder NAME here — if you only know the name, use folder_name instead." }, "folder_name": { "type": "string", "description": "The NAME of an existing folder to place this media (file or folder) into, used when you do not have the folder's exact id (e.g. a folder you just created this turn). The server resolves the name; if several folders share it, it returns candidates so you can ask the user which one. Prefer parent_gid when you already hold the exact id. Omit both to use the library root." }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Optional custom cover IMAGE url for a video upload (same as media library thumbnailUrl). Use when the user supplies a cover image. Ignored for folders. Do not combine with thumb_offset — send one or the other." }, "thumb_offset": { "type": "number", "minimum": 0, "description": "Optional video frame offset in seconds used as the thumbnail (same as media library thumb_offset). Use when the user asks for the frame at N seconds. Ignored for folders. Do not combine with thumbnail_url — send one or the other." } }, "required": [ "type" ], "additionalProperties": false }, "createOrUpdateAutomationRequest": { "type": "object", "properties": { "automation_id": { "type": "string", "description": "Automation id (24-char hex). Omit to create a new automation; provide it to update an existing one." }, "profile_id": { "type": "integer", "description": "Profile id this automation runs on. Required when creating. Ignored on update (an automation cannot move profiles). Use the `POST /v2/profiles/search` endpoint to resolve it." }, "name": { "type": "string", "description": "Automation name. Required when creating." }, "triggers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dm", "comment", "comment_live", "story_reply", "review", "mention", "share" ], "description": "The INCOMING event that starts the automation: what someone else does to the profile, never what the automation sends back. \"dm\" fires when someone sends the profile a DM; \"comment\" fires when someone comments on a post. This list and actions[].action share the words \"dm\" and \"comment\", so a request phrased as \"make it a DM instead of a comment reply\" is about the ACTION, not this field. Leave the trigger as whatever the automation listens for. One of: dm, comment, comment_live, story_reply, review, mention, share." }, "id": { "type": "string", "description": "Existing trigger id from the `POST /v2/automations/get` endpoint. Include it on update to keep this trigger (and its stats and post links); omit it for a brand-new trigger." }, "target_type": { "type": "string", "enum": [ "all", "specific" ], "description": "For comment / story triggers: \"all\" to listen on every post, or \"specific\" for selected posts." }, "target_id": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post, reel, or story id this trigger listens on. For a Vista Social post that is scheduled but not yet published, prefix the publication id with an underscore, for example \"_65f0ab...\"." }, "url": { "type": "string", "description": "Optional canonical URL of the target post." }, "thumbnail_url": { "type": "string", "description": "Optional thumbnail URL of the target post." }, "message": { "type": "string", "description": "Optional caption/text of the target post." }, "media_type": { "type": "string", "description": "Optional media type of the target post." }, "permalink": { "type": "string", "description": "Optional permalink of the target post." } }, "required": [ "id" ], "additionalProperties": false }, "description": "The specific posts/reels/stories to listen on when target_type is \"specific\"." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Only fire when the incoming message/comment matches one of these keywords." }, "exclude_keywords": { "type": "array", "items": { "type": "string" }, "description": "Never fire when the incoming message/comment matches one of these keywords." }, "match_whole_word": { "type": "boolean", "description": "Match keywords as whole words only instead of substrings." }, "intent": { "type": "string", "description": "AI intent description that must be detected to fire. Requires the advanced DM automations plan feature." }, "intents": { "type": "array", "items": { "type": "string" }, "description": "Multiple AI intent descriptions. Requires the advanced DM automations plan feature." }, "non_followers_message": { "type": "string", "description": "Instagram only: message sent when the user is not a follower." }, "sentiments": { "type": "array", "items": { "type": "string" }, "description": "Optional sentiment filters for the trigger." }, "ratings": { "type": "object", "properties": { "rating_from": { "type": "number", "description": "Lowest star rating that fires the trigger." }, "rating_to": { "type": "number", "description": "Highest star rating that fires the trigger." } }, "required": [ "rating_from", "rating_to" ], "additionalProperties": false, "description": "For review triggers: the star-rating range that fires. Requires the advanced DM automations plan feature." }, "enabled": { "type": "boolean", "description": "Whether this trigger is active. Defaults to true." } }, "required": [ "type" ], "additionalProperties": false }, "minItems": 1, "description": "What starts the automation. Required when creating. On update, providing this REPLACES the trigger list, so send the full set (call the `POST /v2/automations/get` endpoint first, keep each trigger id you want to preserve)." }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "dm", "opening_dm", "comment", "delay", "data", "mark_complete", "apply_labels", "create_task", "create_zendesk_ticket", "send_email", "hide_comment", "remove_comment" ], "description": "The OUTGOING step the automation performs when it fires: what it sends or does, never what started it. \"dm\" sends a direct message to the person who triggered it; \"comment\" posts a public reply on their comment. To change what the automation LISTENS for, edit triggers[].type instead. One of: dm, opening_dm, comment, delay, data, mark_complete, apply_labels, create_task, create_zendesk_ticket, send_email, hide_comment, remove_comment." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ai", "open", "text", "image", "video", "document", "delay", "card", "data", "mark_complete", "apply_labels", "create_task", "create_zendesk_ticket", "send_email", "hide_comment", "remove_comment" ], "description": "Content kind for this variant. One of: ai, open, text, image, video, document, delay, card, data, mark_complete, apply_labels, create_task, create_zendesk_ticket, send_email, hide_comment, remove_comment." }, "text": { "type": "string", "description": "Message text. Required for text, ai, and open variants." }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Button label shown to the user." }, "url": { "type": "string", "description": "URL opened when the button is tapped." } }, "required": [ "title", "url" ], "additionalProperties": false }, "description": "Optional tappable buttons (text, ai, and card variants)." }, "knowledge_gid": { "type": "string", "description": "Knowledge base id for an ai variant so replies are grounded in that knowledge base." }, "button_label": { "type": "string", "description": "Call-to-action label for an opening_dm (open) variant." }, "media_gid": { "type": "string", "description": "Media library id. Required for image, video, and document variants. Optional cover for a card. Optional image on a text or ai variant only when the action is comment. Use the `POST /v2/media/search` endpoint or the `POST /v2/media/create` endpoint to obtain it." }, "delay": { "type": "integer", "description": "Delay in milliseconds for a delay variant. Max 30000 per delay, 120000 total across the automation." }, "title": { "type": "string", "description": "Card title. Required for a card variant." }, "subtitle": { "type": "string", "description": "Optional card subtitle." }, "url": { "type": "string", "description": "Optional card tap-through URL." }, "complete_message": { "type": "string", "description": "Data collection: message sent once every field has been collected." }, "expired_message": { "type": "string", "description": "Data collection: message sent when an in-progress collection expires." }, "skip_message": { "type": "string", "description": "Data collection: message shown when the user skips." }, "expire_after": { "type": "integer", "description": "Data collection: minutes before an in-progress collection expires." }, "items": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "Prompt shown to the user when collecting this field." }, "type": { "type": "string", "enum": [ "text", "email", "phone", "number", "url", "date", "first_name", "last_name" ], "description": "Field type. One of: text, email, phone, number, url, date, first_name, last_name." }, "name": { "type": "string", "description": "Human-readable field name." }, "field": { "type": "string", "description": "Machine key used when the collected value is exported." }, "retry_message": { "type": "string", "description": "Optional message shown when the answer fails validation." }, "update_contact": { "type": "boolean", "description": "Save this value onto the contact record when true." } }, "required": [ "message", "type", "name", "field" ], "additionalProperties": false }, "description": "Data collection: ordered list of fields to collect from the user." }, "destination": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email", "rest", "slack" ], "description": "Where collected data is delivered: email, rest (webhook), or slack." }, "value": { "type": "string", "description": "Delivery target: an email address, a webhook URL, or a Slack webhook URL." } }, "required": [ "type", "value" ], "additionalProperties": false, "description": "Data collection: where the collected data is delivered." }, "task": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message", "general", "publication", "report", "idea" ], "description": "Task type. Defaults to \"message\" for automation-created tasks." }, "category": { "type": "string", "enum": [ "general", "sales", "support" ], "description": "Task category: general, sales, or support." }, "assigned_to": { "type": "integer", "description": "Assign to a specific team member user id. Provide either assigned_to or assigned_to_group." }, "assigned_to_group": { "type": "string", "description": "Assign to a team user label/group name. Provide either assigned_to or assigned_to_group." }, "routing": { "type": "string", "enum": [ "none", "capacity", "roundrobin" ], "description": "How to pick an assignee inside a group. Defaults to none." }, "notes": { "type": "string", "description": "Task notes / description." }, "priority": { "type": "boolean", "description": "Mark the created task as priority." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Labels to apply to the created task." } }, "required": [ "category" ], "additionalProperties": false, "description": "create_task variant: the task to create when the automation fires." }, "zendesk_ticket": { "type": "object", "properties": { "profile_gid": { "type": "integer", "description": "Zendesk-connected profile id. Defaults to the automation profile when omitted." }, "subject": { "type": "string", "description": "Ticket subject line." }, "description": { "type": "string", "description": "Ticket description / body." }, "priority": { "type": "string", "description": "Zendesk priority (for example low, normal, high, urgent)." }, "type": { "type": "string", "description": "Zendesk ticket type (for example question, incident, problem, task)." }, "requester_id": { "type": "string", "description": "Optional Zendesk requester id." }, "assignee_id": { "type": "string", "description": "Optional Zendesk assignee id." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional Zendesk tags." } }, "required": [ "subject" ], "additionalProperties": false, "description": "create_zendesk_ticket variant: the Zendesk ticket to open when the automation fires." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "apply_labels variant: inbox labels to apply." }, "users": { "type": "array", "items": { "type": "integer" }, "description": "send_email variant: recipient team member user ids." }, "emails": { "type": "array", "items": { "type": "string" }, "description": "send_email variant: recipient email addresses." }, "user_groups": { "type": "array", "items": { "type": "string" }, "description": "send_email variant: recipient user label/group names." } }, "required": [ "type" ], "additionalProperties": false }, "minItems": 1, "description": "One or more content variants for this action. Multiple same-type variants are rotated at random (A/B). Every variant must share a type compatible with the action." } }, "required": [ "action", "variants" ], "additionalProperties": false }, "minItems": 1, "description": "The ordered steps the automation runs when it fires. Required when creating. On update, providing this REPLACES the action list, so send the full ordered set." }, "save_type": { "type": "string", "enum": [ "draft", "save_and_set_live" ], "description": "Use \"save_and_set_live\" to activate the automation on save, or \"draft\" to save it paused. Defaults to \"draft\" on create; on update, omit to leave the current active state unchanged. To pause/activate an existing automation prefer the `POST /v2/automations/status` endpoint." }, "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "description": "Schedule window: days the automation may run (0 = Sunday ... 6 = Saturday). Omit to run every day." }, "hours_from": { "type": "integer", "minimum": 0, "maximum": 23, "description": "Schedule window: first hour of the day (0-23) the automation may run." }, "hours_to": { "type": "integer", "minimum": 0, "maximum": 23, "description": "Schedule window: last hour of the day (0-23) the automation may run." }, "timezone": { "type": "string", "description": "Timezone for the schedule window, for example \"America/New_York\"." }, "sequence": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Priority when several automations match the same event (lower runs first, 0-100)." }, "exclusive": { "type": "boolean", "description": "When true, stop evaluating other automations after this one matches. Defaults to true." }, "once_per_user": { "type": "boolean", "description": "When true, fire at most once per inbox user. Defaults to false." } }, "additionalProperties": false }, "createOrUpdateIdeaRequest": { "type": "object", "properties": { "idea_id": { "type": "string", "description": "Optional idea id. Provide it to update an existing idea." }, "message": { "type": "string", "description": "\n Idea message. Required for create when idea_id is not provided.\n If you don't have more information, you can ask the user about it and wait until you have the information.\n " }, "media_url": { "type": "array", "items": { "type": "string" }, "description": "Optional links to images/videos/documents. For update, when provided this replaces attachments with converted media." }, "user_ids": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "description": "Optional participant user ids as numbers, for example [4021, 5533]. Use the `POST /v2/users/list` endpoint to resolve ids." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Optional labels for this idea. On update these are ADDED (additive — existing labels are kept); to remove labels use labels_to_remove." }, "labels_to_remove": { "type": "array", "items": { "type": "string" }, "description": "Optional labels to REMOVE from an existing idea on update. Labels not currently on the idea are ignored. Ignored when creating an idea." }, "profile_group_ids": { "type": "array", "items": { "type": "string" }, "description": "\n Optional profile group ids associated with the idea. Use ids from the `POST /v2/profile-groups/list` endpoint or the `POST /v2/profile-groups/search` endpoint.\n When creating an idea in Ask Vista and this is omitted, the runtime applies the conversation's selected profile groups.\n " } }, "additionalProperties": false }, "createOrUpdatePostRequest": { "type": "object", "properties": { "publication_id": { "type": "string", "description": "Optional publication id. When provided, updates that existing post instead of creating a new one." }, "profile_id": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": "integer" }, "minItems": 1 } ], "description": "Profile ID(s) confirmed by user (required for create). Pass an array to post to multiple profiles in one call. Always resolve and confirm with user before submitting." }, "publish_at": { "type": "string", "minLength": 1, "description": "Publish date in ISO 8601. For concrete datetimes, include timezone in the value (for example \"2026-03-14T14:00:00-04:00\"), or use one of \"now\", \"queue_last\", \"queue_available\", \"queue_next\". Optional; when omitted on create, \"now\" is used." }, "timezone": { "type": "string", "description": "Timezone for this request in long IANA format (for example \"America/New_York\"). If omitted, runtime derives and sends one." }, "message": { "type": "string", "description": "Post message. Required if neither media_url nor media_ids are provided." }, "media_url": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "description": "Media URLs to attach." }, "media_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Array of existing media library ids to attach, for example [\"64a1b2c3d4e5f6a7b8c9d0e1\",\"12345\"]. Each id is a 24-char hex id or a numeric library id from the `POST /v2/media/search` endpoint or the `POST /v2/media/create` endpoint. Numeric ids may be passed as numbers or strings." }, "thumbnail_media_url": { "type": "string", "format": "uri", "description": "Optional custom thumbnail URL for video posts." }, "thumbnail_media_offset": { "type": "number", "minimum": 0, "description": "Optional thumbnail offset in seconds for video posts." }, "draft": { "type": "boolean", "description": "Save/create as draft instead of scheduling or publishing." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Labels to tag the post, for example [\"launch\",\"q3\"]. Pass an array (a single comma-separated string is also accepted). On update these are ADDED to the post's existing labels (additive, not a replacement). To remove labels, use labels_to_remove." }, "labels_to_remove": { "type": "array", "items": { "type": "string" }, "description": "Labels to remove from an existing post on update, for example [\"draft\"]. Pass an array (a single comma-separated string is also accepted). Labels that are not currently on the post are ignored. Ignored when creating a post." }, "workflow_gid": { "type": "string", "description": "Workflow GID for multi-step approval flow. Use the `POST /v2/workflows/list` endpoint to let user select a workflow. Cannot be combined with reviewer_user_gid. OMIT this field entirely if not using a workflow — do NOT pass null." }, "reviewer_user_gid": { "type": "integer", "description": "Numeric user ID (integer) to assign as direct reviewer. Use current_user_id from session context ONLY when user explicitly refers to themselves (\"me\"/\"myself\"/\"I'll review\"). Call the `POST /v2/users/list` endpoint for any other phrasing (team member, colleague, specific name). Cannot be combined with workflow_gid. OMIT this field entirely if not assigning a reviewer — do NOT pass null." }, "note_to_reviewer": { "type": "string", "description": "Optional note shown to workflow approvers or direct reviewer." }, "shortening": { "type": "boolean", "description": "Enable default link shortening." }, "publishing_mode": { "type": "string", "enum": [ "auto", "reminder_notification" ], "description": "Publishing mode. Default is \"auto\". Use \"reminder_notification\" only when user explicitly asks for reminder-based publishing." }, "device_gid": { "type": "string", "description": "Device GID for reminder notifications. Required when publishing_mode is \"reminder_notification\". Use the `POST /v2/devices/list` endpoint to discover valid ids." }, "customization": { "type": "object", "properties": { "message": { "type": "string", "description": "Per-profile message override. Replaces the top-level message for this profile only. Because one customization object is applied to every profile in the call, use one call per profile when the text differs. Applies to: all networks." }, "boost_gid": { "type": "string", "description": "Boost configuration id. Applies to: all networks." }, "video_processing": { "type": "boolean", "description": "Override video processing preference. Applies to: all networks." }, "image_processing": { "type": "boolean", "description": "Override image processing preference. Applies to: all networks." }, "delete_after": { "type": "string", "description": "Auto-delete the post after it publishes. ISO-8601 with offset (for example \"2026-08-01T10:00:00-04:00\"), same convention as publish_at. Only applies on networks that support post deletion. Applies to: all networks." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "media_gid": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "description": "Follow-up comments posted in order after the post publishes. Each item is an object keyed by \"message\", for example [{\"message\": \"First comment\"}]. Any other key is discarded. Applies to: twitter, facebook, linkedin, youtube, instagram, tiktok, threads, bluesky, vimeo." }, "like": { "type": "boolean", "description": "Like the published post if supported. Applies to: twitter, linkedin, youtube, instagram, bluesky." }, "publish_as_image": { "type": "boolean", "description": "Applies to: twitter, googlebusiness, bluesky." }, "for_super_followers_only": { "type": "boolean", "description": "Applies to: twitter." }, "is_paid_partnership": { "type": "boolean", "description": "Applies to: twitter, instagram, tiktok." }, "is_ai_generated": { "type": "boolean", "description": "Applies to: twitter, facebook, youtube, instagram, tiktok." }, "reply_settings": { "type": "string", "enum": [ "mentionedUsers", "following" ], "description": "Applies to: twitter." }, "tagged_users": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "name": {}, "username": {} }, "additionalProperties": true }, "description": "Applies to: twitter." }, "publish_as": { "type": "string", "description": "Applies to: facebook, linkedin, snapchat, vistapage." }, "title": { "type": "string", "description": "Accepted and stored but has no organic effect. Facebook link and text posts cannot set a custom link headline through the API (Meta deprecated link-preview editing), the composer has no Facebook title field, and publish does not read this value. Video titles come from the media item, not this field. Applies to: facebook, reddit, pinterest, tiktok, tumblr." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Applies to: facebook, youtube." }, "age_min": { "type": "number", "description": "Applies to: facebook." }, "age_max": { "type": "number", "description": "Applies to: facebook." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Applies to: facebook." }, "relationship_status": { "type": "string", "enum": [ "SINGLE", "IN RELATIONSHIP", "MARRIED", "ENGAGED" ], "description": "Applies to: facebook." }, "call_to_action": { "type": "string", "description": "Applies to: facebook, googlebusiness." }, "location": { "type": "object", "properties": { "id": {}, "name": {}, "latitude": {}, "longitude": {}, "address": {} }, "additionalProperties": true, "description": "Place tag. TikTok location tags carry no coordinates, so TikTok takes {id,name,address} while Facebook and Instagram take {id,name,latitude,longitude}. Applies to: facebook, instagram, tiktok." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "mention": {} }, "additionalProperties": true }, "description": "Applies to: facebook." }, "collaborators": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "name": {} }, "additionalProperties": true }, "description": "Applies to: facebook." }, "geoLocations": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "name": {} }, "additionalProperties": true }, "description": "Applies to: linkedin." }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Applies to: linkedin." }, "video_title": { "type": "string", "description": "Applies to: youtube, vimeo." }, "privacyStatus": { "type": "string", "enum": [ "public", "private", "unlisted" ], "description": "Applies to: youtube." }, "madeForKids": { "type": "boolean", "description": "Applies to: youtube." }, "notifySubscribers": { "type": "boolean", "description": "Applies to: youtube." }, "embeddable": { "type": "boolean", "description": "Applies to: youtube." }, "category_name": { "type": "string", "description": "Applies to: youtube." }, "playlist_name": { "type": "string", "description": "Applies to: youtube." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Applies to: youtube, tumblr." }, "subreddit": { "type": "string", "description": "Applies to: reddit." }, "subreddit_name": { "type": "string", "description": "Applies to: reddit." }, "flair_id": { "type": "string", "description": "Applies to: reddit." }, "flair_text": { "type": "string", "description": "Applies to: reddit." }, "media_type": { "type": "string", "enum": [ "IMAGE", "VIDEO", "CAROUSEL", "REELS", "STORY", "TRIAL_REELS" ], "description": "Applies to: instagram." }, "graduation_strategy": { "type": "string", "enum": [ "MANUAL", "PERFORMANCE" ], "description": "Applies to: instagram." }, "share_to_feed": { "type": "boolean", "description": "Applies to: instagram." }, "media_audio_type": { "type": "string", "enum": [ "MUSIC", "ORIGINAL_SOUND" ], "description": "Reels only. Applies to: instagram." }, "media_audio": { "type": "object", "properties": { "id": {}, "title": {}, "artist": {}, "thumbnail": {}, "preview_url": {}, "media_audio_type": {}, "video_volume": {}, "audio_volume": {}, "duration": {} }, "additionalProperties": true, "description": "Reels only. id is an audio_id from the Instagram audio search. Sent as audio_configuration when media_audio_type is MUSIC or ORIGINAL_SOUND. Applies to: instagram, tiktok." }, "branded_content_sponsors": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "username": {} }, "additionalProperties": true }, "description": "Applies to: instagram." }, "comments_enabled": { "type": "boolean", "description": "Applies to: instagram, tiktok." }, "collaborator_tags": { "type": "array", "items": { "type": "string" }, "description": "Co-author usernames to invite (omit the @). Supported on feed image posts, Reels, and carousels. Not supported on Stories or Trial Reels; Instagram forbids collaborators on a trial reel, so that combination will not publish as tagged. Applies to: instagram." }, "user_tags": { "type": "array", "items": { "type": "object", "properties": { "media_gid": {}, "x": {}, "y": {}, "username": {} }, "additionalProperties": true }, "description": "Applies to: instagram." }, "product_tags": { "type": "array", "items": { "type": "object", "properties": { "media_gid": {}, "product_id": {}, "product_name": {}, "x": {}, "y": {} }, "additionalProperties": true }, "description": "Applies to: instagram." }, "board_name": { "type": "string", "description": "Preferred board name; server resolves to board_id/board_id_name. Applies to: pinterest." }, "board_id": { "type": "string", "description": "Applies to: pinterest." }, "board_id_name": { "type": "string", "description": "Applies to: pinterest." }, "section_name": { "type": "string", "description": "Optional section name; server resolves to section_id/section_id_name. Applies to: pinterest." }, "section_id": { "type": "string", "description": "Applies to: pinterest." }, "section_id_name": { "type": "string", "description": "Applies to: pinterest." }, "description": { "type": "string", "description": "Applies to: pinterest, snapchat." }, "color": { "type": "string", "description": "Optional pin dominant color as a hex value (for example \"#6E7874\"). Sent to Pinterest as dominant_color on create. Invalid values are ignored. Pinterest may still replace it with a color derived from the image. Applies to: pinterest." }, "link": { "type": "string", "description": "Applies to: pinterest." }, "duets_enabled": { "type": "boolean", "description": "Applies to: tiktok." }, "stitches_enabled": { "type": "boolean", "description": "Applies to: tiktok." }, "is_promotional_content": { "type": "boolean", "description": "Applies to: tiktok." }, "privacy_level": { "type": "string", "enum": [ "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY" ], "description": "Applies to: tiktok." }, "auto_add_music": { "type": "boolean", "description": "Applies to: tiktok." }, "save_to_profile": { "type": "boolean", "description": "Applies to: snapchat." }, "locale": { "type": "string", "description": "Applies to: snapchat." }, "slug": { "type": "string", "description": "Applies to: tumblr." }, "reply_control": { "type": "string", "enum": [ "everyone", "accounts_you_follow", "mentioned_only" ], "description": "Applies to: threads." }, "hide_replies": { "type": "boolean", "description": "Applies to: threads." }, "tagged_countries": { "type": "array", "items": { "type": "string" }, "description": "Applies to: threads." }, "post_type": { "type": "string", "enum": [ "STANDARD", "EVENT", "OFFER", "ALERT" ], "description": "Applies to: googlebusiness." }, "alert_type": { "type": "string", "enum": [ "ALERT_TYPE_UNSPECIFIED", "COVID_19" ], "description": "Applies to: googlebusiness." }, "event_title": { "type": "string", "description": "Applies to: googlebusiness." }, "event_start": { "type": "string", "description": "Applies to: googlebusiness." }, "event_end": { "type": "string", "description": "Applies to: googlebusiness." }, "offer": { "type": "object", "properties": { "coupon": {}, "terms": {} }, "additionalProperties": true, "description": "Applies to: googlebusiness." }, "grid_images_links": { "type": "array", "items": { "type": "object", "properties": { "media_gid": {}, "link": {} }, "additionalProperties": true }, "description": "Applies to: vistapage." } }, "additionalProperties": true, "description": "Network-specific post options. This is a **flat** object — put fields directly inside `customization` (do **not** nest them under a network name). Which keys apply is determined by each target profile's network; when posting to multiple profiles, only the keys relevant to each network are used. Unknown keys are passed through to the backend unchanged.\n\n**Common fields** (all networks):\n- `message` — `string`. Per-profile message override. Replaces the top-level message for this profile only. Because one customization object is applied to every profile in the call, use one call per profile when the text differs.\n- `boost_gid` — `string`. Boost configuration id.\n- `video_processing` — `boolean`. Override video processing preference.\n- `image_processing` — `boolean`. Override image processing preference.\n- `delete_after` — `string`. Auto-delete the post after it publishes. ISO-8601 with offset (for example \"2026-08-01T10:00:00-04:00\"), same convention as publish_at. Only applies on networks that support post deletion.\n\n**Per-network fields:**\n\n_Twitter / X_\n- `comments` — `array}>`. Follow-up comments posted in order after the post publishes. Each item is an object keyed by \"message\", for example [{\"message\": \"First comment\"}]. Any other key is discarded.\n- `like` — `boolean`. Like the published post if supported.\n- `publish_as_image` — `boolean`\n- `for_super_followers_only` — `boolean`\n- `is_paid_partnership` — `boolean`\n- `is_ai_generated` — `boolean`\n- `reply_settings` — one of `mentionedUsers`, `following`\n- `tagged_users` — `array`\n\n_Facebook_\n- `comments` — `array}>`. Follow-up comments posted in order after the post publishes. Each item is an object keyed by \"message\", for example [{\"message\": \"First comment\"}]. Any other key is discarded.\n- `publish_as` — one of `IMAGE`, `CAROUSEL`, `REELS`, `VIDEO`, `STORY`, `ARTICLE`\n- `title` — `string`. Accepted and stored but has no organic effect. Facebook link and text posts cannot set a custom link headline through the API (Meta deprecated link-preview editing), the composer has no Facebook title field, and publish does not read this value. Video titles come from the media item, not this field.\n- `countries` — `array`\n- `age_min` — `number`\n- `age_max` — `number`\n- `gender` — one of `MALE`, `FEMALE`\n- `relationship_status` — one of `SINGLE`, `IN RELATIONSHIP`, `MARRIED`, `ENGAGED`\n- `call_to_action` — `string`\n- `location` — `object{id,name,latitude,longitude}`\n- `mentions` — `array`\n- `collaborators` — `array`\n- `is_ai_generated` — `boolean`\n\n_LinkedIn_\n- `comments` — `array}>`. Follow-up comments posted in order after the post publishes. Each item is an object keyed by \"message\", for example [{\"message\": \"First comment\"}]. Any other key is discarded.\n- `like` — `boolean`. Like the published post if supported.\n- `publish_as` — one of `POLL`, `IMAGE`, `VIDEO`, `CAROUSEL`, `ARTICLE`\n- `geoLocations` — `array`\n- `languages` — `array`\n\n_YouTube_\n- `comments` — `array}>`. Follow-up comments posted in order after the post publishes. Each item is an object keyed by \"message\", for example [{\"message\": \"First comment\"}]. Any other key is discarded.\n- `like` — `boolean`. Like the published post if supported.\n- `video_title` — `string`\n- `privacyStatus` — one of `public`, `private`, `unlisted`\n- `madeForKids` — `boolean`\n- `is_ai_generated` — `boolean`\n- `notifySubscribers` — `boolean`\n- `embeddable` — `boolean`\n- `category_name` — `string`\n- `playlist_name` — `string`\n- `tags` — `array`\n- `countries` — `array`\n\n_Reddit_ — requires `subreddit` OR `subreddit_name`\n- `subreddit` — `string`\n- `subreddit_name` — `string`\n- `title` — `string`. Reddit post title, trimmed to 300 characters. If omitted, the first sentence of the message is used. A post must have a message or a title.\n- `flair_id` — `string`\n- `flair_text` — `string`\n\n_Instagram_\n- `comments` — `array}>`. Follow-up comments posted in order after the post publishes. Each item is an object keyed by \"message\", for example [{\"message\": \"First comment\"}]. Any other key is discarded.\n- `like` — `boolean`. Like the published post if supported.\n- `media_type` — one of `IMAGE`, `VIDEO`, `CAROUSEL`, `REELS`, `STORY`, `TRIAL_REELS`\n- `graduation_strategy` — one of `MANUAL`, `PERFORMANCE`\n- `share_to_feed` — `boolean`\n- `media_audio_type` — one of `MUSIC`, `ORIGINAL_SOUND`. Reels only.\n- `media_audio` — `object{id,title?,artist?,thumbnail?,preview_url?,media_audio_type?,video_volume?,audio_volume?}`. Reels only. id is an audio_id from the Instagram audio search. Sent as audio_configuration when media_audio_type is MUSIC or ORIGINAL_SOUND.\n- `is_paid_partnership` — `boolean`\n- `is_ai_generated` — `boolean`\n- `branded_content_sponsors` — `array`\n- `comments_enabled` — `boolean`\n- `collaborator_tags` — `array`. Co-author usernames to invite (omit the @). Supported on feed image posts, Reels, and carousels. Not supported on Stories or Trial Reels; Instagram forbids collaborators on a trial reel, so that combination will not publish as tagged.\n- `user_tags` — `array`\n- `product_tags` — `array`\n- `location` — `object{id,name,latitude,longitude}`\n\n_Pinterest_ — requires `board_name` OR `board_id` OR `board_id_name`\n- `board_name` — `string`. Preferred board name; server resolves to board_id/board_id_name.\n- `board_id` — `string`\n- `board_id_name` — `string`\n- `section_name` — `string`. Optional section name; server resolves to section_id/section_id_name.\n- `section_id` — `string`\n- `section_id_name` — `string`\n- `description` — `string`\n- `title` — `string`. Pin title, trimmed to 100 characters. Optional.\n- `color` — `string`. Optional pin dominant color as a hex value (for example \"#6E7874\"). Sent to Pinterest as dominant_color on create. Invalid values are ignored. Pinterest may still replace it with a color derived from the image.\n- `link` — `string`\n\n_TikTok_\n- `comments` — `array}>`. Follow-up comments posted in order after the post publishes. Each item is an object keyed by \"message\", for example [{\"message\": \"First comment\"}]. Any other key is discarded.\n- `comments_enabled` — `boolean`\n- `duets_enabled` — `boolean`\n- `stitches_enabled` — `boolean`\n- `is_promotional_content` — `boolean`\n- `is_paid_partnership` — `boolean`\n- `is_ai_generated` — `boolean`\n- `privacy_level` — one of `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY`\n- `title` — `string`. Post title, trimmed to 90 characters. Optional and used mainly for photo posts; video captions come from the message.\n- `auto_add_music` — `boolean`\n- `media_audio` — `object{id,title?,artist?,thumbnail?,preview_url?,duration?,video_volume?,audio_volume?}`. Commercial Music Library track. id must be a song_clip_id from /discovery/cml/trending_list/, since TikTok rejects any other identifier. Video posts send the track plus both volumes; photo posts send the id alone because TikTok rejects volume and trim fields there. Mutually exclusive with auto_add_music.\n- `location` — `object{id,name,address?}`. Place tag. TikTok location tags carry no coordinates, so TikTok takes {id,name,address} while Facebook and Instagram take {id,name,latitude,longitude}.\n\n_Snapchat_\n- `publish_as` — one of `STORY`, `SPOTLIGHT`, `SAVED_STORY`\n- `save_to_profile` — `boolean`\n- `description` — `string`\n- `locale` — `string`\n\n_Tumblr_\n- `tags` — `array`\n- `slug` — `string`\n- `title` — `string`. Post title for text and link posts. On photo and video posts it is used as the caption instead. Optional.\n\n_Threads_\n- `comments` — `array}>`. Follow-up comments posted in order after the post publishes. Each item is an object keyed by \"message\", for example [{\"message\": \"First comment\"}]. Any other key is discarded.\n- `reply_control` — one of `everyone`, `accounts_you_follow`, `mentioned_only`\n- `hide_replies` — `boolean`\n- `tagged_countries` — `array`\n\n_Google Business_\n- `call_to_action` — one of `BOOK`, `ORDER`, `SHOP`, `LEARN_MORE`, `SIGN_UP`, `CALL`\n- `post_type` — one of `STANDARD`, `EVENT`, `OFFER`, `ALERT`\n- `alert_type` — one of `ALERT_TYPE_UNSPECIFIED`, `COVID_19`\n- `event_title` — `string`\n- `event_start` — `date`\n- `event_end` — `date`\n- `offer` — `object{coupon,terms}`\n- `publish_as_image` — `boolean`\n\n_Bluesky_\n- `comments` — `array}>`. Follow-up comments posted in order after the post publishes. Each item is an object keyed by \"message\", for example [{\"message\": \"First comment\"}]. Any other key is discarded.\n- `like` — `boolean`. Like the published post if supported.\n- `publish_as_image` — `boolean`\n\n_Vista Page_\n- `publish_as` — one of `POST`, `IMAGE_GRID`\n- `grid_images_links` — `array`\n\n_Vimeo_\n- `comments` — `array}>`. Follow-up comments posted in order after the post publishes. Each item is an object keyed by \"message\", for example [{\"message\": \"First comment\"}]. Any other key is discarded.\n- `video_title` — `string`\n\n**Examples** (the `customization` object only):\n- Facebook Reel: `{ \"publish_as\": \"REELS\" }`\n- Instagram Carousel (required for multiple media): `{ \"media_type\": \"CAROUSEL\" }`\n- Pinterest pin: `{ \"board_name\": \"Inspiration\", \"section_name\": \"Workspace\", \"title\": \"Pin title\", \"link\": \"https://example.com\", \"color\": \"#6E7874\" }`\n- Reddit: `{ \"subreddit_name\": \"AskReddit\", \"title\": \"My title\", \"flair_text\": \"Discussion\" }`\n- TikTok: `{ \"privacy_level\": \"PUBLIC_TO_EVERYONE\", \"comments_enabled\": true, \"is_paid_partnership\": false }`\n- YouTube: `{ \"video_title\": \"My video\", \"privacyStatus\": \"public\", \"category_name\": \"Education\", \"tags\": [\"howto\"] }`" }, "_profile_display_names": { "type": "array", "items": { "type": "string" }, "description": "Runtime-injected. Resolved profile display names. Read-only — do not set this yourself." }, "_workflow_display_name": { "type": "string", "description": "The human-readable name of the selected workflow (from the `POST /v2/workflows/list` endpoint). Pass this so the confirmation card can show the workflow name to the user." }, "_reviewer_display_name": { "type": "string", "description": "The human-readable name of the reviewer (e.g. \"John Smith\"). Pass this so the confirmation card can show who will review the post." } }, "additionalProperties": false }, "createOrUpdateProjectRequest": { "type": "object", "properties": { "project_id": { "type": "string", "description": "Provide to update an existing project; omit to create one." }, "profile_group_id": { "type": "string", "description": "Profile group that owns a new project (from the `POST /v2/profile-groups/list` endpoint). Required when creating." }, "name": { "type": "string", "description": "Project name. Required when creating." }, "description": { "type": "string", "description": "Project description." }, "color": { "type": "string", "description": "Hex color for the project (e.g. \"#2E7CF6\")." }, "icon": { "type": "string", "description": "Icon key for the project." }, "is_default": { "type": "boolean", "description": "Make this the profile group's default destination for new tasks." }, "archived": { "type": "boolean", "description": "Update only: true archives the project, false restores it." } }, "additionalProperties": false }, "createOrUpdateSharedCalendarRequest": { "type": "object", "properties": { "shared_calendar_id": { "type": "string", "description": "Omit to create a new link. Provide the _id (from the `POST /v2/shared-calendars/list` endpoint) to update an existing link." }, "title": { "type": "string", "minLength": 1, "description": "Display name shown in Shared links and on the public page. Required. If you don't have more information, you can ask the user about it and wait until you have the information." }, "profile_ids": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Profile ids (the numeric id from the `POST /v2/profiles/search` endpoint) whose posts appear on the shared calendar, for example [11, 73]. At least one required. On UPDATE this may only remove profiles (must be a subset of the current profiles)." }, "from_date": { "type": "string", "description": "Start of the visible date range in YYYY-MM-DD. Required. If you don't have more information, you can ask the user about it and wait until you have the information." }, "to_date": { "type": "string", "description": "End of the visible date range in YYYY-MM-DD. Optional; open-ended when omitted." }, "timezone": { "type": "string", "description": "IANA timezone for the calendar (e.g. \"America/New_York\"). Required. Use the session timezone if known, otherwise ask. If you don't have more information, you can ask the user about it and wait until you have the information." }, "statuses": { "type": "array", "items": { "type": "string" }, "description": "Optional post-status filter (e.g. PUBLISHED, DRAFT, REVIEW, APPROVED, FAILED). Empty = all statuses." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Optional post-label filter." }, "queue_labels": { "type": "array", "items": { "type": "string" }, "description": "Optional queue-label filter." }, "author_user_ids": { "type": "array", "items": { "type": "number" }, "description": "Optional filter by post author (Vista Social team-member user gids from the `POST /v2/users/list` endpoint)." }, "post_content_types": { "type": "array", "items": { "type": "string" }, "description": "Optional content-type filter." }, "boost_statuses": { "type": "array", "items": { "type": "string" }, "description": "Optional boost-status filter." }, "advocacy_statuses": { "type": "array", "items": { "type": "string" }, "description": "Optional advocacy-status filter." }, "evergreen_statuses": { "type": "array", "items": { "type": "string" }, "description": "Optional evergreen-status filter." }, "can_comment": { "type": "boolean", "description": "Allow viewers to leave comments. Default false." }, "show_external_posts": { "type": "boolean", "description": "Show posts published outside Vista Social. Default true." }, "show_review_posts": { "type": "boolean", "description": "Show posts still in review/approval. Default false." }, "password": { "type": "string", "description": "Optional access passphrase viewers must enter to open the link. Not a Vista Social account password; shown in clear text in the app." }, "expires": { "type": "string", "description": "Optional expiration date in YYYY-MM-DD. After this date the link stops working." }, "auto_delete": { "type": "boolean", "description": "When true AND expires is set, the link is soft-deleted automatically after it expires. Ignored without expires." }, "recipient_emails": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "Up to 5 email addresses to send the invitation to. Provide ONLY to send/resend invitations; omit to skip email entirely." }, "email_subject": { "type": "string", "maxLength": 70, "description": "Invitation email subject (max 70 chars). Used only when recipient_emails is provided." }, "email_body": { "type": "string", "maxLength": 500, "description": "Invitation email body (max 500 chars). Used only when recipient_emails is provided." } }, "required": [ "title", "profile_ids", "from_date", "timezone" ], "additionalProperties": false }, "createOrUpdateTaskRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "Provide to update an existing task; omit to create a new one." }, "project_id": { "type": "string", "description": "Destination project for a new task (from the `POST /v2/projects/list` endpoint). Ignored on update (a task keeps its project)." }, "profile_group_id": { "type": "string", "description": "On create with project_id omitted: the profile group whose default project receives the task (from the `POST /v2/profile-groups/list` endpoint)." }, "title": { "type": "string", "description": "Task title. Required when creating (task_id omitted). On update it can be renamed but not cleared, so omit it to keep the current title." }, "description": { "type": "string", "description": "Task description / notes." }, "status_key": { "type": "string", "description": "Status key from the project (the `POST /v2/projects/list` endpoint statuses[].key). Moving into a Done/Closed status completes the task." }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high", "urgent" ], "description": "Task priority." }, "assignee_user_ids": { "type": "array", "items": { "type": "string" }, "description": "Assignees. Each entry is a user_gid (from the `POST /v2/users/list` endpoint or a project's members), an email, a full name, or \"me\" (the caller). Resolved against the project group: a name/email that matches nobody is rejected, and a user_gid that is not a member of that group is SKIPPED while the call still succeeds (the response says which ids were skipped). So resolve people with the `POST /v2/users/list` endpoint profile_group_id= rather than from the whole account roster. On update this replaces the assignee set; pass an empty array to unassign everyone." }, "watcher_user_ids": { "type": "array", "items": { "type": "string" }, "description": "Watchers, using the same reference formats as assignees. On update this replaces the watcher set; empty array clears it." }, "assigned_to_group": { "type": "string", "description": "Create only: assign to a team by user label (for example \"Support\") instead of a named person. One member is picked by workload. Cannot be used to reassign an existing task; pass assignee_user_ids for that." }, "routing": { "type": "string", "enum": [ "roundrobin", "capacity" ], "description": "How to pick the member for assigned_to_group: roundrobin (least recently assigned) or capacity (fewest open tasks). Defaults to roundrobin. Ignored without assigned_to_group." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Labels. On update this replaces the label set; pass an empty array to clear." }, "start_date": { "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2})?)?$", "description": "Start date. Format as YYYY-MM-DD, or YYYY-MM-DD HH:MM for a specific time. On update, pass an empty string to clear." }, "due_date": { "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2})?)?$", "description": "Due date. Format as YYYY-MM-DD, or YYYY-MM-DD HH:MM for a specific time. On update, pass an empty string to clear." }, "due_has_time": { "type": "boolean", "description": "Set true when due_date includes a specific time." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Custom field id, or its exact name (from the `POST /v2/task-fields/list` endpoint / the `POST /v2/tasks/get` endpoint)." }, "value": { "type": "string", "description": "Value as text: digits for a number, YYYY-MM-DD for a date, \"true\" or \"false\" for a checkbox, the option label or key for a dropdown, a URL for a link field. Pass an empty string to clear a field that is not required." } }, "required": [ "field", "value" ], "additionalProperties": false }, "description": "Values for the project's user-defined fields. Only the fields you list are touched. Fields the project does not have are rejected, so read them with the `POST /v2/task-fields/list` endpoint first." }, "parent_task_id": { "type": "string", "description": "Parent task id in the same project to nest under (from the `POST /v2/tasks/search` endpoint or the `POST /v2/tasks/get` endpoint). On update, pass an empty string to detach to the top level. For embedded checklist rows use the `POST /v2/tasks/checklist/add` endpoint instead." }, "order": { "type": "number", "description": "Manual sort order within the task's lane (update only)." }, "links_add": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "publication", "inbox_message", "idea", "report", "vista_page", "listener", "automation", "advocacy", "smart_publisher" ], "description": "Linked object type." }, "ref_id": { "type": "string", "description": "Id of the linked object." } }, "required": [ "type", "ref_id" ], "additionalProperties": false }, "description": "Associations to add on update (e.g. a publication or inbox_message this task relates to)." }, "links_remove": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Link ids to remove from the task on update." } }, "additionalProperties": false }, "createOrUpdateUserRequest": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "Vista Social user id of an existing member to update (from the `POST /v2/users/list` endpoint). Omit to invite a new member." }, "email": { "type": "string", "format": "email", "description": "\n Team member email. Required. When inviting, this is the new member's email; when updating, pass the member's current email (from the `POST /v2/users/list` endpoint) unless changing it.\n If you don't have more information, you can ask the user about it and wait until you have the information.\n " }, "first_name": { "type": "string", "description": "\n Team member first name. Required. When updating, pass the current value (from the `POST /v2/users/list` endpoint) unless changing it.\n If you don't have more information, you can ask the user about it and wait until you have the information.\n " }, "last_name": { "type": "string", "description": "\n Team member last name. Required. When updating, pass the current value (from the `POST /v2/users/list` endpoint) unless changing it.\n If you don't have more information, you can ask the user about it and wait until you have the information.\n " }, "language": { "type": "string", "description": "Optional ISO language code for the invitation email and the member's system language, e.g. \"en\", \"es\"." }, "access": { "type": "string", "enum": [ "MANAGER", "RESTRICTED" ], "description": "\n Account role. \"MANAGER\" = account admin with full access to every profile group (omit profile_groups).\n \"RESTRICTED\" = access limited to the profile groups listed in profile_groups. Required.\n " }, "profile_groups": { "type": "array", "items": { "type": "object", "properties": { "profile_group_id": { "type": "string", "description": "Profile group id from the `POST /v2/profile-groups/list` endpoint or the `POST /v2/profile-groups/search` endpoint." }, "role": { "type": "string", "enum": [ "ADMIN", "RESTRICTED" ], "description": "ADMIN = full access to this profile group (all permissions MANAGE). RESTRICTED = use the per-feature permissions below. Defaults to RESTRICTED." }, "publish": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE", "CONTRIBUTOR" ], "description": "Publishing permission. CONTRIBUTOR can schedule posts but they require review (needs the approval-workflow feature). Defaults to MANAGE." }, "reports": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE" ], "description": "Reports permission. Defaults to MANAGE." }, "inbox": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE" ], "description": "Inbox permission. Defaults to MANAGE." }, "reviews": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE" ], "description": "Reviews permission. Defaults to MANAGE." }, "listen": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE" ], "description": "Listening permission. Defaults to MANAGE." }, "profiles": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE" ], "description": "Connected-profiles management permission. Defaults to MANAGE." }, "pages": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE" ], "description": "Vista Pages permission. Defaults to MANAGE." }, "ideas": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE" ], "description": "Ideas permission. Defaults to MANAGE." }, "tasks": { "type": "string", "enum": [ "NONE", "MANAGE" ], "description": "Tasks permission. Defaults to MANAGE." }, "automations": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE" ], "description": "Automations permission. Defaults to MANAGE." }, "medias": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE" ], "description": "Media library permission. Defaults to MANAGE." }, "dashboard": { "type": "string", "enum": [ "NONE", "VIEW", "MANAGE" ], "description": "Dashboard permission. VIEW is read-only; MANAGE can also customize the widget layout. Defaults to MANAGE." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Optional labels/groups for this member within this profile group." } }, "required": [ "profile_group_id" ], "additionalProperties": false }, "description": "Required when access=\"RESTRICTED\": one entry per profile group the member should access, each with a role and optional per-feature permissions. On update this is a partial change (unlisted groups are untouched). Omit when access=\"MANAGER\"." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Optional team-member labels/groups. For account MANAGERs these tag the member across all groups." } }, "required": [ "email", "first_name", "last_name", "access" ], "additionalProperties": false }, "createOrUpdateUserResponse": { "type": "object", "description": "Standard envelope returned by this endpoint on success.", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true for a 2xx response." }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Vista Social user id of the invited or updated member." } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "ok", "data" ] }, "createProfileGroupRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "\n Name of the profile group. This is field is required. \n If you don't have more information, you can ask the user about it and wait until you have the information.\n " }, "type": { "type": "string", "enum": [ "AGENCY", "BRAND", "CLIENT", "CAMPAIGN", "GROUP", "PROJECT" ], "description": "Type of the profile group to help you identify this group." }, "picture_url": { "type": "string", "description": "\n Link to an image to help visually identify the profile group. \n This can be a brand logo. \n Verify that links are valid and accessible. \n Offer user to help find image if they do not have it.\n This field is optional and can be left blank.\n " }, "max_users": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Maximum number of users allowed in the profile group (1-1000). Use 0 for no limit. Optional; defaults to no limit." }, "max_profiles": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Maximum number of profiles allowed in the profile group (1-1000). Use 0 for no limit. Optional; defaults to no limit." }, "country": { "type": "string", "description": "2 letter country code where this profile group is located. This field is required." }, "timezone": { "type": "string", "description": "Timezone of the profile group. This field is required. Use timezone from the `POST /v2/timezones/list` endpoint tool." }, "publish_now_delay": { "type": "integer", "minimum": 0, "maximum": 59, "description": "Minutes of delay before publish-now posts go live (0-59). 0 = publish immediately. Optional." }, "publish_killswitch": { "type": "boolean", "description": "Set true to disable all publishing for this group, false to keep publishing enabled. Optional." }, "blocked_networks": { "type": "array", "items": { "type": "string" }, "description": "Social network codes that cannot be connected to this group (for example [\"facebook\",\"tiktok\"]). Use the `POST /v2/networks/list` endpoint for valid codes. Pass an empty array for no restrictions. Optional." }, "shortener": { "type": "boolean", "description": "Set true to enable link shortening for this group, false to disable it. Optional." } }, "required": [ "name", "type", "country", "timezone" ], "additionalProperties": false }, "createTrendListenerRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 25, "description": "Display name for the listener. Max 25 chars (existing listener constraint)." }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "x_news_trend", "x_trends", "youtube_trending", "dataforseo_trends", "brave_news_trend" ] }, "minItems": 1, "maxItems": 4, "description": "Array of trend sources to monitor, for example [\"x_news_trend\"]. Pass an array even for a single source (at least one, up to four). Default to [\"x_news_trend\"] if the user did not specify." }, "keywords": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "Optional keywords/phrases to narrow matches. If omitted, the source itself is the filter (e.g. \"all trending news in US\"). Use for brand/topic-specific tracking." }, "exclude_keywords": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "Keywords whose presence in a trend disqualifies the match. Useful for filtering out competitors or unrelated namesakes." }, "regions": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "ISO country codes to monitor. Empty = global / user profile region." }, "languages": { "type": "array", "items": { "type": "string" }, "description": "ISO 639-1 language codes. Empty = all languages." }, "notify": { "type": "boolean", "description": "When true, route significant matches through the existing listener notification pipeline." } }, "required": [ "name", "sources" ], "additionalProperties": false }, "deletePostRequest": { "type": "object", "properties": { "publication_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ], "description": "A single publication id, or an array of publication ids, to delete. Use the `POST /v2/posts/search` endpoint to find ids when the user references posts by text/date." }, "reason": { "type": "string", "description": "Optional deletion note recorded in the post history and notifications." } }, "required": [ "publication_id" ], "additionalProperties": false }, "deletePostResponse": { "type": "object", "description": "Standard envelope returned by this endpoint on success.", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true for a 2xx response." }, "data": { "type": "object", "properties": { "deleted": { "type": "array", "items": { "type": "string" }, "description": "Publication ids that were deleted." }, "problems": { "type": "array", "items": { "type": "string" }, "description": "Human-readable reasons for ids that were not deleted, for example the post does not exist or was already removed. Empty on a full success. A call can return 200 with deleted empty and problems populated when every id failed." } }, "required": [ "deleted", "problems" ], "additionalProperties": false } }, "required": [ "ok", "data" ] }, "deleteSharedCalendarRequest": { "type": "object", "properties": { "shared_calendar_id": { "type": "string", "description": "The _id of a single shared calendar link to delete (from the `POST /v2/shared-calendars/list` endpoint). Use this or shared_calendar_ids." }, "shared_calendar_ids": { "type": "array", "items": { "type": "string" }, "description": "Multiple shared calendar link _ids to delete in one call (from the `POST /v2/shared-calendars/list` endpoint). Use this to revoke several links at once instead of calling the tool repeatedly." } }, "additionalProperties": false }, "deleteTaskRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The Vista Work task id to delete (from the `POST /v2/tasks/search` endpoint or the `POST /v2/tasks/get` endpoint)." } }, "required": [ "task_id" ], "additionalProperties": false }, "deleteTaskChecklistItemRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The Vista Work task id that owns the checklist (from the `POST /v2/tasks/get` endpoint)." }, "checklist_item_id": { "type": "string", "description": "Checklist row id to remove (from the `POST /v2/tasks/get` endpoint.subtasks[].id)." } }, "required": [ "task_id", "checklist_item_id" ], "additionalProperties": false }, "deleteTaskCommentRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The Vista Work task id that owns the comment (from the `POST /v2/tasks/get` endpoint)." }, "comment_id": { "type": "string", "description": "Comment id to remove (from the `POST /v2/tasks/get` endpoint.comments[].id)." } }, "required": [ "task_id", "comment_id" ], "additionalProperties": false }, "deleteUserRequest": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "Vista Social user id of the member to remove. Use the `POST /v2/users/list` endpoint to resolve it. Required." }, "profile_group_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Profile group ids to remove the member from. Required, at least one. Use only ids from this member's profile_groups (the `POST /v2/users/get` endpoint) - do not use the `POST /v2/profile-groups/list` endpoint. Pass all of the member's group ids to offboard them entirely." } }, "required": [ "user_id", "profile_group_ids" ], "additionalProperties": false }, "deleteUserResponse": { "type": "object", "description": "Standard envelope returned by this endpoint on success.", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true for a 2xx response." }, "data": { "type": "object", "properties": {}, "additionalProperties": false, "description": "Empty object on success. Failures use the error envelope, not this payload." } }, "required": [ "ok", "data" ] }, "duplicateProjectRequest": { "type": "object", "properties": { "project_id": { "type": "string", "description": "Source project id to clone (from the `POST /v2/projects/list` endpoint)." }, "name": { "type": "string", "description": "Name for the new project. Defaults to \" (Copy)\"." }, "mode": { "type": "string", "enum": [ "everything", "customize" ], "description": "everything (default) copies all supported slices; customize uses the options flags." }, "options": { "type": "object", "properties": { "due_dates": { "type": "boolean", "description": "Copy task due dates. Defaults to true." }, "attachments": { "type": "boolean", "description": "Copy task attachments. Defaults to true." }, "subtasks": { "type": "boolean", "description": "Copy nested board tasks (parent_task_id). Defaults to true." }, "tags": { "type": "boolean", "description": "Copy task labels. Defaults to true." }, "checklists": { "type": "boolean", "description": "Copy embedded checklist rows. Defaults to true." }, "custom_fields": { "type": "boolean", "description": "Attach source custom-field definitions to the copy. Defaults to true." }, "assignees": { "type": "boolean", "description": "Copy task assignees. Defaults to true." } }, "additionalProperties": false, "description": "Only used when mode is customize. Omitted flags default to true." } }, "required": [ "project_id" ], "additionalProperties": false }, "findMediaRequest": { "type": "object", "properties": { "path": { "type": "string", "enum": [ "library", "external" ], "description": "Search path: \"library\" or \"external\"." }, "media_type": { "type": "string", "enum": [ "image", "video" ], "description": "Media type filter. Required for external path." }, "source": { "type": "string", "enum": [ "unsplash", "pexels", "giphy", "instagram_hashtag", "instagram_user" ], "description": "External source. Required for external path." }, "q": { "type": "string", "description": "Search query. Optional for unsplash/pexels/giphy. Required for instagram_hashtag and instagram_user." }, "limit": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Maximum number of external results to return (external path only). Defaults to 10. Maximum is 10." }, "from": { "type": "string", "description": "External pagination cursor/offset." }, "page": { "type": "integer", "minimum": 0, "description": "Pagination page. For path=\"library\", page is 0-based. For path=\"external\", page is forwarded as provider page (typically 1-based)." }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Library filter: labels to match (e.g. [\"campaign\",\"summer\"])." }, "usage": { "type": "string", "enum": [ "used_media", "unused_media" ], "description": "Library filter: used or unused media." }, "profile_group_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Library filter: profile group ids (maps to entities)." }, "created_by_user_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Library filter: creator user ids as strings, for example [\"4021\",\"5533\"]. Numeric ids may be passed as numbers or strings. Use the `POST /v2/users/list` endpoint to resolve ids." }, "extensions": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Library filter: file extensions (for example [\"jpg\",\"png\",\"mp4\"])." }, "folder_name": { "type": "string", "minLength": 1, "description": "Library folder navigation BY NAME: the human title of the folder the user wants to open (e.g. \"Test\"). The server resolves the real folder id for you — prefer this whenever the user refers to a folder by name. If several folders share the name you get back candidates to disambiguate. Omit for the library root." }, "parent_gid": { "type": "string", "minLength": 1, "description": "Library folder navigation BY ID: the folder's own 24-char hex \"id\" from a folders[] entry you received in THIS turn (or a disambiguation candidate). Use this only when you already hold the exact id; otherwise use folder_name. Omit for the library root." }, "no_dynamic": { "type": "boolean", "description": "Library filter: exclude dynamic media variants when true." }, "include_metadata": { "type": "boolean", "description": "Library only. Set true ONLY when the user asks about file details — dimensions, resolution, aspect ratio, file size, format/extension, duration, or which brand/profile-group a media belongs to. Default (omit/false) returns the lean core fields (id, title, description, url, thumbnail_url, created, labels, type, ai_generated). Leave it off for ordinary \"show me / list my media\" requests." }, "include_semantic": { "type": "boolean", "description": "Library only. Set true ONLY when the user asks an ANALYSIS question about the media — platform fit (e.g. \"is this good for LinkedIn?\"), hook strength, scroll-stop power, pacing, mood, strengths/weaknesses, or brand safety. This rehydrates the heavy per-item `semantic` block, so keep it off for plain listing/selection and narrow the result (q / labels / limit) to the item(s) in question first." } }, "required": [ "path" ], "additionalProperties": false }, "findProfileGroupsRequest": { "type": "object", "properties": { "profile_group_name": { "type": "string", "description": "Optional profile group name filter (partial match)." }, "profile_group_id": { "type": "string", "description": "Optional profile group id for detailed lookup." } }, "additionalProperties": false }, "findProfileGroupsResponse": { "type": "object", "description": "Standard envelope returned by this endpoint on success.", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true for a 2xx response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "profile_group_id": { "type": "string", "description": "Profile group id. Use this as profile_group_id on other endpoints." }, "name": { "type": "string", "description": "Profile group display name." }, "type": { "type": "string", "description": "Group type, for example brand." }, "timezone": { "type": "string", "description": "IANA timezone for the group. Empty string when unset." }, "details_lookup_status": { "type": "string", "enum": [ "ok", "failed" ], "description": "Present on a single-id lookup. ok when brand and limit details loaded; failed when they did not." }, "details_lookup_error": { "type": "string", "description": "Present when details_lookup_status is failed." }, "brand_voice": { "type": "string", "description": "Brand voice text. Only on a single-id lookup that succeeded." }, "brand_voice_configured": { "type": "boolean", "description": "True when brand_voice has non-empty text after stripping HTML." }, "brand_safety": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether brand safety / compliance checks are on for this group." }, "policy": { "type": "string", "description": "Brand safety policy text. Empty when unset." } }, "additionalProperties": true }, "brand_settings": { "type": "object", "properties": { "brand_voice": { "type": "string" }, "brand_voice_configured": { "type": "boolean" }, "brand_safety": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether brand safety / compliance checks are on for this group." }, "policy": { "type": "string", "description": "Brand safety policy text. Empty when unset." } }, "additionalProperties": true } }, "additionalProperties": true, "description": "Duplicate of brand_voice / brand_safety for callers that read the nested settings object." }, "group_limits": { "type": "object", "properties": { "max_users": { "type": "integer", "nullable": true, "description": "Seat cap for the group. Null means no cap." }, "max_profiles": { "type": "integer", "nullable": true, "description": "Connected-profile cap. Null means no cap." } }, "additionalProperties": true }, "publishing_safety": { "type": "object", "properties": { "publish_now_delay_minutes": { "type": "number", "description": "Minutes to wait after a publish-now action before the post goes live. 0 means no delay." }, "publishing_enabled": { "type": "boolean", "description": "False when publishing from this group is paused." } }, "additionalProperties": true } }, "required": [ "profile_group_id", "name", "type", "timezone" ], "additionalProperties": true, "description": "A profile group. List results only include profile_group_id, name, type, and timezone. Pass profile_group_id in the request to also receive brand, limit, and publishing-safety details." }, "description": "Matching profile groups. Empty array when nothing matched." } }, "required": [ "ok", "data" ] }, "findProfilesRequest": { "type": "object", "properties": { "profile_name": { "type": "string", "description": "Optional profile name to search for. Alias of q." }, "q": { "type": "string", "description": "Optional search query for profile name." }, "profile_group_id": { "type": "string", "description": "Optional profile group id to filter by." }, "profile_id": { "type": "number", "description": "Optional exact profile id lookup." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "network", "network_code", "username", "nickname", "profile_url", "picture_url", "sic_code", "industry", "industry_group", "status", "status_detail" ] }, "default": [ "id", "name", "status" ], "description": "Optional array of field names to include, for example [\"id\",\"name\",\"network\"]. Pass an array even for a single field. Defaults to [\"id\",\"name\",\"status\"]. Allowed: id, name, network, network_code, username, nickname, profile_url, picture_url, sic_code, industry, industry_group, status, status_detail. industry is the profile's specific industry label (resolved from its SIC code); industry_group is the broader industry bucket used by the industry benchmark. Both are null when the profile has no industry set. status is the connection-health state (ok, access_blocked, error, warning, suspended, initializing); status_detail is a short user-facing sentence explaining the issue and the recommended fix (null when status is ok)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Max results (default 50)." }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Pagination offset (default 0)." } }, "additionalProperties": false }, "findProfilesResponse": { "type": "object", "description": "Standard envelope returned by this endpoint on success.", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true for a 2xx response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Numeric profile id. Pass this as profile_id on other endpoints." }, "name": { "type": "string", "description": "Display name of the connected social profile." }, "network": { "type": "string", "description": "Human-readable network label, for example \"Facebook Page\"." }, "network_code": { "type": "string", "description": "Network slug, for example \"facebook\" or \"instagram\"." }, "username": { "type": "string", "nullable": true, "description": "Handle on the network, when the network has one." }, "nickname": { "type": "string", "nullable": true, "description": "Optional nickname stored on the profile." }, "profile_url": { "type": "string", "nullable": true, "description": "Public URL of the profile on the network." }, "picture_url": { "type": "string", "nullable": true, "description": "Avatar image URL." }, "sic_code": { "type": "string", "nullable": true, "description": "SIC industry code when one is set on the profile." }, "industry": { "type": "string", "nullable": true, "description": "Specific industry label resolved from the SIC code. Null when the profile has no industry set." }, "industry_group": { "type": "string", "nullable": true, "description": "Broader industry bucket used by the industry benchmark. Null when the profile has no industry set." }, "status": { "type": "string", "enum": [ "ok", "access_blocked", "error", "warning", "suspended", "initializing" ], "description": "Connection health. ok: healthy. access_blocked: reconnect the profile. error: Vista Social could not load it, reconnect. warning: a permission or scope gap, fix it on the network and reconnect. suspended: banned, reconnecting will not help. initializing: still setting up." }, "status_detail": { "type": "string", "nullable": true, "description": "Short sentence explaining the issue and the fix. Null when status is ok." } }, "additionalProperties": false, "description": "One connected social profile. Only requested fields are present. Default fields when you omit the request fields list: id, name, status. Allowed fields: id, name, network, network_code, username, nickname, profile_url, picture_url, sic_code, industry, industry_group, status, status_detail." }, "description": "Matching profiles. Empty array when nothing matched. Field set follows the request fields list." } }, "required": [ "ok", "data" ] }, "findTrendingNowRequest": { "type": "object", "properties": { "region": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (e.g. \"US\", \"GB\"). Defaults to \"US\"." }, "vertical": { "type": "string", "description": "Optional Vista vertical tag (e.g. \"fashion\", \"fitness\", \"finance\") to bias the seed keywords. Omit for global feed." }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "x_trends", "x_news", "youtube", "google", "news", "niche" ] }, "description": "Array of source families to restrict the response to, for example [\"x_trends\",\"news\"]. Pass an array even for a single source. Allowed: x_trends, x_news, youtube, google, news, niche." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Max trends to return. Default 25, max 50." } }, "additionalProperties": false }, "getAutomationRequest": { "type": "object", "properties": { "automation_id": { "type": "string", "description": "Automation id (24-char hex) from the `POST /v2/automations/search` endpoint." } }, "required": [ "automation_id" ], "additionalProperties": false }, "getAutomationResultsRequest": { "type": "object", "properties": { "automation_id": { "type": "string", "description": "Automation id (24-char hex) from the `POST /v2/automations/search` endpoint." }, "dateFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date for the timeline (YYYY-MM-DD). Defaults to 30 days ago." }, "dateTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date for the timeline (YYYY-MM-DD). Defaults to today." }, "include": { "type": "array", "items": { "type": "string", "enum": [ "summary", "timeline", "contacts" ] }, "description": "Which sections to return: summary, timeline, and/or contacts. Omit to return all three." } }, "required": [ "automation_id" ], "additionalProperties": false }, "getDevicesRequest": { "type": "object", "properties": { "profile_group_ids": { "type": "array", "items": { "type": "string" }, "description": "Optional profile group ids (entities) to scope devices. If omitted, active profile groups for current user are used." } }, "additionalProperties": false }, "getInboxResponsePerformanceReportRequest": { "type": "object", "properties": { "profile_id": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Profile IDs to include in the inbox response performance report. Use profile_id from the `POST /v2/profiles/search` endpoint." }, "dateFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)." }, "dateTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)." }, "priorFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional comparison period start date (YYYY-MM-DD)." }, "priorTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional comparison period end date (YYYY-MM-DD)." }, "template_id": { "type": "string", "description": "Optional report template id." }, "timezone": { "type": "string", "description": "Timezone (e.g. \"America/Los_Angeles\")." } }, "required": [ "profile_id" ], "additionalProperties": false }, "getInboxStatsRequest": { "type": "object", "properties": { "profile_id": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Profile IDs. Use profile_id from the `POST /v2/profiles/search` endpoint. At least one profile is required." }, "types": { "type": "array", "items": { "type": "string" }, "description": "Optional inbox item types to include: comment, message, review, mention, share." }, "types_exclude": { "type": "array", "items": { "type": "string" }, "description": "Optional inbox item types to exclude." }, "q": { "type": "string", "minLength": 1, "description": "Optional free-text search filter on message content and sender name. Use to count items matching a keyword/hashtag (e.g. q=\"SMMW26\") before listing." }, "sentiment": { "type": "array", "items": { "type": "string", "enum": [ "positive", "negative", "neutral", "mixed", "none" ] }, "description": "Optional sentiment filter for stats." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Optional label filter for stats." }, "seen": { "type": "boolean", "description": "Optional seen/read filter. true=seen only, false=unseen only, omit=all." }, "acknowledged": { "type": "boolean", "description": "Optional completed filter mapped to inbox acknowledged flag. true=completed/acknowledged only, false=incomplete/unacknowledged only." }, "starred": { "type": "boolean", "description": "Optional starred filter. true=starred only, false=not-starred only." }, "has_replies": { "type": "boolean", "description": "Optional responded-to filter. false=not yet replied (unanswered), true=already replied. Use false to count unanswered items; false also defaults to excluding Complete (acknowledged) and spam items unless you set those explicitly, matching the dashboard waiting count. Distinct from acknowledged (manually marked complete) and seen (read)." }, "dark": { "type": "boolean", "description": "Optional dark filter. true=dark only, false=non-dark only." }, "spam": { "type": "boolean", "description": "Optional spam filter. true=spam only, false=non-spam only." }, "own": { "type": "boolean", "description": "Whether to include owned messages/posts/comments. Defaults to false (non-owned inbound only). Set true only when user explicitly asks to include owned items." }, "received_after": { "type": "string", "description": "Optional ISO 8601 datetime lower bound for received time filtering. If omitted with received_before, last-30-days default is used." }, "received_before": { "type": "string", "description": "Optional ISO 8601 datetime upper bound for received time filtering. If omitted with received_after, last-30-days default is used." }, "group_by": { "type": "string", "enum": [ "none", "type", "profile", "network", "day" ], "description": "Optional stats grouping dimension. Defaults to none (single total)." } }, "required": [ "profile_id" ], "additionalProperties": false }, "getIndustryBenchmarkRequest": { "type": "object", "properties": { "profile_id": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Profile IDs to benchmark. Use profile_id from the `POST /v2/profiles/search` endpoint." }, "dateFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)." }, "dateTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)." }, "priorFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional comparison period start date (YYYY-MM-DD)." }, "priorTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional comparison period end date (YYYY-MM-DD)." }, "template_id": { "type": "string", "description": "Optional report template id." }, "timezone": { "type": "string", "description": "Timezone (e.g. \"America/Los_Angeles\")." } }, "required": [ "profile_id" ], "additionalProperties": false }, "getOptimalPublishTimesRequest": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "object", "properties": { "profile_id": { "type": "number", "description": "Profile ID" }, "timezone": { "type": "string", "description": "Timezone for this profile (e.g. \"America/Los_Angeles\")." } }, "required": [ "profile_id" ], "additionalProperties": false }, "description": "List of profiles (with optional timezones) to analyze." }, "profile_id": { "type": "array", "items": { "type": "number" }, "description": "Profile IDs. Use profile_id from the `POST /v2/profiles/search` endpoint." }, "timezone": { "type": "string", "description": "Default timezone to use when a target timezone is not provided. Defaults to the user timezone or UTC." }, "combined": { "type": "boolean", "description": "If true, returns optimal times for all selected profiles combined. If false (default), returns optimal times per profile." } }, "additionalProperties": false }, "getPostRequest": { "type": "object", "properties": { "post_id": { "type": "string", "description": "Post id (returned by the `POST /v2/posts/save` endpoint or the `POST /v2/posts/search` endpoint)." } }, "required": [ "post_id" ], "additionalProperties": false }, "getProfileMetricsRequest": { "type": "object", "properties": { "profile_ids": { "type": "array", "items": { "type": "number" }, "description": "Profile IDs scope (one or many). Provide profile_ids or profile_group_ids. Use profile_id from the `POST /v2/profiles/search` endpoint tool." }, "profile_group_ids": { "type": "array", "items": { "type": "string" }, "description": "Profile group scope. Provide profile_ids or profile_group_ids. Use profile_group_id from the `POST /v2/profile-groups/list` endpoint or the `POST /v2/profile-groups/search` endpoint tool." }, "from_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "From date. Use YYYY-MM-DD format. If omitted, defaults to 30 days before to_date." }, "to_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "To date. Use YYYY-MM-DD format. If omitted, defaults to today." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Optional output field whitelist. If provided, each returned row will include only these keys plus profile_gid, date, and network (always returned for reconciliation)." }, "latest_only": { "type": "boolean", "description": "When true, return only the most recent row per profile instead of all daily rows. ONLY use this for point-in-time snapshot questions (e.g. \"current followers\", \"how many followers do I have now\"). NEVER use latest_only for time-series, trend, chart, or \"over time\" requests — those require a full date range without latest_only, and the response already returns one row per profile per day. Do not call this tool in a per-day loop with latest_only; use a single range call instead." }, "response_mode": { "type": "string", "enum": [ "compact", "raw" ], "default": "compact", "description": "Output mode. compact (default) returns { meta, columns, rows, summary }. raw preserves legacy output shape." } }, "additionalProperties": false }, "getProfileQueuesRequest": { "type": "object", "properties": { "profile_id": { "type": "number", "description": "Profile ID" } }, "required": [ "profile_id" ], "additionalProperties": false }, "getPublishedPostPerformanceRequest": { "type": "object", "properties": { "date_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD). Required." }, "date_to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD). Required." }, "profile_ids": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Profile ids to include." }, "profile_group_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Profile group ids to expand into profiles." }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Optional labels filter." }, "metric": { "type": "string", "enum": [ "impressions", "engagement", "likes", "comments", "shares", "clicks", "views", "plays", "saves", "retweets", "quotes" ], "default": "impressions", "description": "Primary ranking metric. Default impressions." }, "secondary_metric": { "type": "string", "enum": [ "engagement", "impressions", "likes", "comments", "shares", "clicks", "views", "plays", "saves", "retweets", "quotes" ], "default": "engagement", "description": "Secondary ranking metric (tiebreaker). Default engagement." }, "sort_order": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc", "description": "Sort direction. Default desc." }, "top_n": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Number of rows to return." }, "include_full_message": { "type": "boolean", "default": false, "description": "When true, returns full message. Default false returns a 25-char preview." }, "fields": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Optional list of fields to include in output rows (in addition to ranking columns)." } }, "required": [ "date_from", "date_to" ], "additionalProperties": false }, "getSentimentReportRequest": { "type": "object", "properties": { "profile_id": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Profile IDs to include in the sentiment report. Use profile_id from the `POST /v2/profiles/search` endpoint." }, "dateFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)." }, "dateTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)." }, "priorFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional comparison period start date (YYYY-MM-DD)." }, "priorTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional comparison period end date (YYYY-MM-DD)." }, "template_id": { "type": "string", "description": "Optional report template id." }, "timezone": { "type": "string", "description": "Timezone (e.g. \"America/Los_Angeles\")." } }, "required": [ "profile_id" ], "additionalProperties": false }, "getTaskRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The Vista Work task id (from the `POST /v2/tasks/search` endpoint or the `POST /v2/tasks/my` endpoint)." } }, "required": [ "task_id" ], "additionalProperties": false }, "getTrendListenerMatchesRequest": { "type": "object", "properties": { "listener_gid": { "type": "string", "minLength": 1, "description": "Listener _id from the `POST /v2/trend-listeners/list` endpoint or the `POST /v2/trend-listeners/create` endpoint." }, "since": { "type": "string", "description": "ISO 8601 datetime — earliest last_seen to include. Defaults to 30 days ago." }, "until": { "type": "string", "description": "ISO 8601 datetime — latest last_seen to include. Defaults to now." }, "min_composite_score": { "type": "number", "minimum": 0, "maximum": 100, "description": "Floor on composite_score. Default 0." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Max matches. Default 25, max 100." } }, "required": [ "listener_gid" ], "additionalProperties": false }, "getUserRequest": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "Vista Social user id of the member to fetch. Resolve it with the `POST /v2/users/list` endpoint. Pass user_id or email." }, "email": { "type": "string", "description": "Email of the member to fetch. Pass user_id or email (user_id wins if both are given)." }, "include_picture": { "type": "boolean", "description": "Optional. Default false. Set true only when you need the member picture/avatar URL." } }, "additionalProperties": false }, "getVistaPagesRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "importVistaPageRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ai", "linkinbio", "bufferstartpage", "bitly", "linktree", "sproutlink" ], "description": "Import source type. This field is required." }, "profile_group_id": { "type": "string", "description": "Profile group id where this Vista Page template will be created. Use profile_group_id from the `POST /v2/profile-groups/list` endpoint or the `POST /v2/profile-groups/search` endpoint. This field is required." }, "url": { "type": "string", "description": "Source URL to import from. Required for non-ai types. For AI type, provide either website url or a prompt." }, "instructions": { "type": "string", "minLength": 100, "maxLength": 2000, "description": "Optional: style, tone, which links to prioritize, etc. For AI type, provide either intructions or website url. Min 100, max 2000 characters." } }, "required": [ "type", "profile_group_id" ], "additionalProperties": false }, "inboxActionRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "star", "unstar", "complete", "incomplete", "spam", "unspam", "read", "unread", "label", "sentiment", "reply" ], "description": "Action to perform. See tool description for required fields per action." }, "inbox_id": { "type": "string", "description": "Inbox message ID from the `POST /v2/inbox/search` endpoint. Required for: label, sentiment, reply." }, "inbox_ids": { "type": "array", "items": { "type": "string" }, "description": "Multiple inbox message IDs from the `POST /v2/inbox/search` endpoint. Use for bulk label actions." }, "conversation_id": { "type": "string", "description": "Conversation ID from the `POST /v2/inbox/search` endpoint. Required for: star, unstar, complete, incomplete, spam, unspam, read, unread, reply." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Labels to ADD for action=label. Additive: these are added to the message's existing labels and do NOT replace them. Provide at least one of labels or labels_to_remove. Example: [\"important\", \"sales\"]." }, "labels_to_remove": { "type": "array", "items": { "type": "string" }, "description": "Labels to REMOVE for action=label. Each must match an existing label on the message exactly. Labels not present are ignored. Example: [\"sales\"]." }, "sentiment": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "positive", "negative", "neutral", "mixed", "none" ], "description": "Sentiment type." }, "reason": { "type": "string", "description": "Why this sentiment is being set." } }, "required": [ "name" ], "additionalProperties": false, "description": "Sentiment to set. Required for action=sentiment." }, "message": { "type": "string", "description": "Message text. Required for action=reply (public reply)." } }, "required": [ "action" ], "additionalProperties": false }, "listAutomationsRequest": { "type": "object", "properties": { "profile_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only include automations on these profile ids. Omit for every profile. Use the `POST /v2/profiles/search` endpoint to resolve ids." }, "q": { "type": "string", "description": "Case-insensitive search on the automation name." }, "trigger_type": { "type": "string", "enum": [ "dm", "comment", "comment_live", "story_reply", "review", "mention", "share" ], "description": "Only include automations with a trigger of this type. One of: dm, comment, comment_live, story_reply, review, mention, share." }, "status": { "type": "string", "enum": [ "active", "paused", "standby" ], "description": "Filter by status: active (live), paused, or standby (live but outside its schedule window)." }, "page": { "type": "integer", "minimum": 0, "description": "Zero-based page number. 20 automations per page." }, "sort_by": { "type": "string", "enum": [ "created_at", "last_chat" ], "description": "Sort field. Defaults to created_at." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction. Defaults to desc." } }, "additionalProperties": false }, "listBoostConfigurationsRequest": { "type": "object", "properties": { "profile_id": { "type": "number", "description": "Profile ID to list boost configurations for." }, "include_configuration": { "type": "boolean", "description": "Whether to include full boost configuration settings. Defaults to true." } }, "required": [ "profile_id" ], "additionalProperties": false }, "listExternalCalendarsRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "listIdeasRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional idea id for specific idea lookup." }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Optional labels filter. Ideas with any matching label are returned." }, "entities": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Optional profile_group_ids filter. If omitted, defaults to profile groups available to the authenticated user." }, "page": { "type": "integer", "minimum": 0, "description": "Optional 0-based page for pagination." }, "path": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Optional folder path as ordered folder IDs from root to current folder (for example [\"69b360072da9e1f1b2e1c7e3\",\"69b360082da9e1f1b2e1c7e4\"]). Omit for root." }, "idea_path": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Alias for path. Folder IDs only (24-char hex ids). Prefer IDs returned by the `POST /v2/ideas/search` endpoint folders[].id." } }, "additionalProperties": false }, "listInboxItemsRequest": { "type": "object", "properties": { "profile_id": { "type": "array", "items": { "type": "number" }, "description": "Profile IDs. Use profile_id from the `POST /v2/profiles/search` endpoint tool. At least one profile is required." }, "types": { "type": "array", "items": { "type": "string", "enum": [ "comment", "message", "review", "mention", "share", "invite" ] }, "description": "Array of inbox item types to include, for example [\"comment\",\"message\"]. Pass an array even for a single type. Allowed: comment, message, review, mention, share, invite. invite covers Instagram collab invites. Omit to return all types." }, "types_exclude": { "type": "array", "items": { "type": "string", "enum": [ "comment", "message", "review", "mention", "share", "invite" ] }, "description": "Array of inbox item types to exclude, for example [\"review\"]. Pass an array even for a single type. Use when the user says \"everything except \". When provided, types may be omitted to mean \"all types except these\"." }, "q": { "type": "string", "description": "Free-text search on message content and sender name. Use when user asks for messages from a specific person or containing specific text." }, "sentiment": { "type": "array", "items": { "type": "string", "enum": [ "positive", "negative", "neutral", "mixed", "none" ] }, "description": "Filter by sentiment. Values: positive, negative, neutral, mixed, none. Pass as array, e.g. [\"positive\"] or [\"negative\",\"neutral\"]." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Filter by one or more labels applied to inbox items, e.g. [\"sales\",\"urgent\"]." }, "dark": { "type": "boolean", "description": "Filter by dark status (ad-originated). IMPORTANT: only comment items can be dark. Pass true to return dark comments, false to return non-dark items." }, "own": { "type": "boolean", "description": "Filter by ownership. own=true means the item was posted by the connected account itself (e.g. your own reply/comment); own=false means inbound items from other people. DEFAULT: when omitted, only inbound items (own=false) are returned — set own=true only when the user explicitly asks to include their own posts/comments/messages." }, "spam": { "type": "boolean", "description": "Filter by spam status (items the user marked as spam in their inbox). Pass true to return only spam, false to exclude spam. Omit to apply no spam filter, except that has_replies=false defaults spam to false (excludes spam) unless you set it explicitly. Otherwise only set this when the user explicitly asks about spam." }, "received_after": { "type": "string", "description": "ISO 8601 datetime — only return items received after this time. Only pass when user explicitly specifies a date/time window. Do not send a default. Do not set this for quantity/recency-only requests like \"last 5 comments\"." }, "received_before": { "type": "string", "description": "ISO 8601 datetime — only return items received before this time. Only pass when user explicitly specifies a date/time window. Do not send a default. Do not set this for quantity/recency-only requests like \"last 5 comments\"." }, "seen": { "type": "boolean", "description": "Filter by seen/read status. Pass true to return only items that have been seen, false to return only unseen/unread items. Omit to return all items regardless of seen status. Use false when the user asks for unread or unseen messages. seen means read/opened only — it does NOT mean handled, acknowledged, or replied." }, "acknowledged": { "type": "boolean", "description": "Filter by acknowledged/completed status (the inbox \"complete\"/\"done\" flag the user sets manually). Pass true for items the user marked done, false for items still open in the queue. Omit to return all. IMPORTANT: acknowledged means \"user marked it complete / does not want to revisit it\" — it does NOT mean read (seen) and does NOT mean replied. Do NOT use acknowledged to find unanswered items; use has_replies for that." }, "starred": { "type": "boolean", "description": "Filter by starred/flagged status. Pass true to return only starred items, false for not-starred. Omit to return all. starred just means the user flagged it for their own reasons — it implies nothing about read/handled/replied state." }, "has_replies": { "type": "boolean", "description": "Filter by whether the item has been responded to. Pass false for items with NO reply yet (unanswered / awaiting a response), true for items that already have at least one reply. Omit to return all. This is the correct filter for \"unanswered\", \"not replied to\", \"awaiting reply\", or \"need a response\". has_replies=false also defaults to excluding Complete (acknowledged) and spam items unless you set those explicitly, so the list and its total match the dashboard waiting count. Do NOT use acknowledged or seen for that — only has_replies reflects whether a reply was actually sent." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "OMIT this parameter for typical listing requests — the default of 20 is the right page size. Only pass limit when the user explicitly names a page size (e.g. \"show 5 most recent\" → limit=5). Range 1-50; the 50 ceiling is a safety cap, not a recommendation. Do NOT pass limit=50 just because the user wants \"everyone\" — use skip-based pagination instead." }, "skip": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set. Default 0. Use skip = page * limit." }, "full_text": { "type": "boolean", "description": "When true, return untruncated message bodies (and untruncated parent.message when include_parent is also true). Default false; messages are truncated to ~140 chars by default to keep listings cheap. Use ONLY when the user explicitly asks for the full text/body of comments/messages." }, "include_parent": { "type": "boolean", "description": "When true, include parent: { url, message, type } on each item. Default false. Use ONLY when the user asks about the original post the comment is on." } }, "required": [ "profile_id" ], "additionalProperties": false }, "listMacrosRequest": { "type": "object", "properties": { "type": { "type": "string", "description": "Macro type to list. Common values are \"message\" (inbox macros) and \"task\"." }, "profile_group_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Optional profile group ids as strings, for example [\"101\",\"102\"], to scope which macros are returned. Use profile_group_id from the `POST /v2/profile-groups/list` endpoint or the `POST /v2/profile-groups/search` endpoint. If omitted, returns macros available to the current user scope." } }, "required": [ "type" ], "additionalProperties": false }, "listMyTasksRequest": { "type": "object", "properties": { "profile_group_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Profile group ids to scope to (from the `POST /v2/profile-groups/list` endpoint). Omit for all accessible groups." }, "timezone": { "type": "string", "description": "IANA timezone for due-date bucketing (e.g. \"America/New_York\"). Defaults to the caller's account timezone." } }, "additionalProperties": false }, "listNetworksRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "listNetworksResponse": { "type": "object", "description": "Standard envelope returned by this endpoint on success.", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true for a 2xx response." }, "data": { "type": "object", "properties": { "networks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Internal network name." }, "id": { "type": "integer", "description": "Numeric network id." }, "code": { "type": "string", "description": "Network slug used as network_code elsewhere, for example facebook." }, "display": { "type": "string", "description": "Label shown in the product, for example \"Facebook Page\"." }, "type": { "type": "string", "description": "Network account type, for example page or business." }, "daily_posts": { "type": "integer", "description": "Daily post cap Vista Social enforces for this network." } }, "required": [ "name", "id", "code", "display", "type", "daily_posts" ], "additionalProperties": false }, "description": "Active networks Vista Social can publish to." } }, "required": [ "networks" ], "additionalProperties": false } }, "required": [ "ok", "data" ] }, "listPostCommentsRequest": { "type": "object", "properties": { "post_id": { "type": "string", "description": "Post id (publication id)." } }, "required": [ "post_id" ], "additionalProperties": false }, "listPostsRequest": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": [ "SCHEDULED", "IN_REVIEW", "APPROVED", "REVIEW", "DRAFT", "REJECTED", "FAILED", "PUBLISHED", "REMINDER_SENT", "REMINDER_REJECTED", "REMINDER_PUBLISHED", "PROCESSING", "DELETED" ] }, "minItems": 1, "description": "Array of status values, for example [\"SCHEDULED\"] or [\"PUBLISHED\",\"FAILED\"]. Pass an array even for a single status. Required in filter mode; omit (and provide publication_ids instead) for direct lookup. Preferred values: SCHEDULED, IN_REVIEW, DRAFT, REJECTED, FAILED, PUBLISHED. Backend aliases APPROVED/REVIEW are also accepted." }, "dateFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD). Ignored in direct-lookup mode (publication_ids)." }, "dateTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD). Ignored in direct-lookup mode (publication_ids)." }, "profile_ids": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Profile ids. Required in filter mode; omit (and provide publication_ids instead) for direct lookup. Provide all relevant profile ids in one call whenever possible." }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Optional label filter. Keeps only posts carrying these labels (case-insensitive). Combine with labels_match to choose ANY vs ALL. Use the literal \"none\" to match posts that have no labels. Applies in filter mode; also refines direct-lookup (publication_ids) results." }, "labels_match": { "type": "string", "enum": [ "any", "all" ], "default": "any", "description": "How to match the labels filter. \"any\" (default) keeps a post if it has at least one requested label; \"all\" requires every requested label. Ignored when labels is omitted." }, "publication_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100, "description": "Direct lookup: up to 100 Vista Social publication ids (24-char hex ids returned as the \"id\" field by the `POST /v2/posts/search` endpoint/the `POST /v2/posts/get` endpoint/the `POST /v2/posts/save` endpoint). Not social-network ids (FB post id, IG media id, Tweet id, etc.). When provided, status / profile_ids / dateFrom / dateTo are ignored, and the response includes one row per owned id (non-owned/unknown ids are silently dropped). Mutually exclusive with status + profile_ids — pick one mode." }, "timezone": { "type": "string", "description": "Timezone (e.g. \"America/Los_Angeles\"). Defaults to user timezone or Etc/UTC." }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Optional max number of posts to return (after filtering)." }, "response_mode": { "type": "string", "enum": [ "compact", "raw" ], "default": "compact", "description": "Output mode. compact (default) returns lightweight rows. raw returns legacy Post[] payload." }, "include_profile": { "type": "boolean", "default": false, "description": "Include full profile object in compact mode. Default false." }, "include_insights": { "type": "boolean", "default": false, "description": "Include the full insights object (works in both compact and raw mode). Required for post-performance ranking (top/best by impressions/engagement) and for any network-specific metric (e.g. TikTok watch time/retention). When true, meta.insight_glossary documents non-obvious fields. Default false." }, "include_media_urls": { "type": "boolean", "default": false, "description": "Include images/videos/documents URL arrays in compact mode. Default false." }, "include_full_message": { "type": "boolean", "default": false, "description": "Return full post text in message field. Default false returns truncated preview to reduce payload size." } }, "additionalProperties": false }, "listProjectsRequest": { "type": "object", "properties": { "profile_group_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Profile group ids to filter by (from the `POST /v2/profile-groups/list` endpoint). Omit to list every accessible group." }, "archived": { "type": "boolean", "description": "Return archived projects instead of active ones. Defaults to false." } }, "additionalProperties": false }, "listSharedCalendarsRequest": { "type": "object", "properties": { "profile_ids": { "type": "array", "items": { "type": "number" }, "description": "Optional profile ids (the numeric id from the `POST /v2/profiles/search` endpoint) to scope the results, for example [11, 73]. A link is returned if it includes any of these profiles. Omit to list every matching link across the account (managers/owners); non-managers must pass profiles they can access or they get an empty list." }, "status": { "type": "string", "enum": [ "active", "expired", "all" ], "description": "active (default) = not yet expired (or no expiration); expired = past expiration; all = every non-deleted link regardless of expiry. All three work account-wide when profile_ids is omitted (managers/owners)." }, "search": { "type": "string", "description": "Case-insensitive substring match on the shared calendar title." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Default 25, max 100." }, "offset": { "type": "integer", "minimum": 0, "description": "Rows to skip for pagination. Default 0." } }, "additionalProperties": false }, "listTaskFieldsRequest": { "type": "object", "properties": { "project_id": { "type": "string", "description": "Only fields that apply to this project (from the `POST /v2/projects/list` endpoint)." }, "profile_group_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Profile group ids to scope fields to (from the `POST /v2/profile-groups/list` endpoint). Ignored when project_id is set." } }, "additionalProperties": false }, "listTasksRequest": { "type": "object", "properties": { "project_id": { "type": "string", "description": "Project id to list tasks from (from the `POST /v2/projects/list` endpoint). Omit to search across projects by title (q required)." }, "profile_group_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Profile group ids to scope a cross-project search (from the `POST /v2/profile-groups/list` endpoint). Only the first is applied." }, "q": { "type": "string", "description": "Text to match against task title/description. Required when project_id is omitted (cross-project search)." }, "status": { "type": "array", "items": { "type": "string" }, "description": "Only tasks in these status keys (from a project's statuses[].key)." }, "assignee_user_id": { "type": "string", "description": "Only tasks assigned to this person: a user_gid, an email, a full name, or \"me\"." }, "priority": { "type": "array", "items": { "type": "string", "enum": [ "none", "low", "medium", "high", "urgent" ] }, "description": "Only tasks with these priorities." }, "label": { "type": "array", "items": { "type": "string" }, "description": "Only tasks carrying these labels." }, "due": { "type": "string", "enum": [ "overdue", "today", "upcoming", "none" ], "description": "Filter by due bucket: overdue, today, upcoming, or none (no due date set)." }, "sort": { "type": "string", "enum": [ "order", "due_date", "priority", "created", "updated" ], "description": "Sort order (project-list mode). Defaults to order." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum tasks to return (1-100). Defaults to 50." }, "timezone": { "type": "string", "description": "IANA timezone used to decide what counts as overdue/today/upcoming (e.g. \"America/New_York\"). Defaults to the caller's account timezone." } }, "additionalProperties": false }, "listTimezonesRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "listTrendListenersRequest": { "type": "object", "properties": { "enabled_only": { "type": "boolean", "description": "When true, returns only enabled (non-paused) listeners. Default false (returns all)." } }, "additionalProperties": false }, "listUsersRequest": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "all", "active", "pending" ], "description": "Optional. Default \"all\". \"active\" = members who have logged in at least once (joined set). \"pending\" = invited but never logged in. Filter server-side instead of scanning the whole roster." }, "q": { "type": "string", "description": "Optional. Case-insensitive substring match on first name, last name, or email. Use it to find a specific person instead of listing everyone." }, "profile_group_id": { "type": "string", "description": "Optional profile group gid (from the `POST /v2/profile-groups/list` endpoint, or the group that owns a project/post). Returns only members of that group, which is who can be assigned work in it. Use it before assigning tasks, watchers or reviewers." }, "include_picture": { "type": "boolean", "description": "Optional. Default false. Set true only when the user explicitly asks for user pictures/avatar URLs." } }, "additionalProperties": false }, "listWorkflowsRequest": { "type": "object", "properties": { "profile_group_ids": { "type": "array", "items": { "type": "string" }, "description": "Profile group ids to filter workflows by. Use selected_primary_profile_group_id from session context." } }, "required": [ "profile_group_ids" ], "additionalProperties": false }, "manageExternalCalendarRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "add", "remove" ], "description": "Action to perform on external calendars." }, "url": { "type": "string", "format": "uri", "description": "External calendar ICS URL to add/remove." }, "color": { "type": "string", "description": "Optional color label for add action. Ignored for remove action." }, "show_external_calendars": { "type": "boolean", "description": "Optional visibility toggle for external calendars in publishing calendar." } }, "required": [ "action", "url" ], "additionalProperties": false }, "manageProjectStatusesRequest": { "type": "object", "properties": { "project_id": { "type": "string", "description": "Project id whose columns to replace (from the `POST /v2/projects/list` endpoint)." }, "statuses": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable status key used by the `POST /v2/tasks/create` endpoint.status_key." }, "name": { "type": "string", "description": "Column label shown on the board." }, "category": { "type": "string", "enum": [ "not_started", "active", "done", "closed" ], "description": "Status type: not_started, active, done, or closed. done/closed complete tasks." }, "order": { "type": "number", "description": "Column order from left to right (0-based)." }, "color": { "type": "string", "description": "Optional hex color for the column (e.g. \"#2E7CF6\")." } }, "required": [ "key", "name", "category", "order" ], "additionalProperties": false }, "description": "Full next statuses array for the project (not a partial patch)." }, "status_migrations": { "type": "array", "items": { "type": "object", "properties": { "from_status_key": { "type": "string", "description": "Status key being removed that still has tasks." }, "to_status_key": { "type": "string", "description": "Remaining status key that should receive those tasks." } }, "required": [ "from_status_key", "to_status_key" ], "additionalProperties": false }, "description": "Required when removing columns that still hold open tasks." } }, "required": [ "project_id", "statuses" ], "additionalProperties": false }, "removeTaskAttachmentRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The Vista Work task id (from the `POST /v2/tasks/get` endpoint)." }, "attachment_id": { "type": "string", "description": "Attachment id to remove (from the `POST /v2/tasks/get` endpoint.attachments[].id)." } }, "required": [ "task_id", "attachment_id" ], "additionalProperties": false }, "searchProfileGroupsRequest": { "type": "object", "properties": { "profile_group_name": { "type": "string", "description": "Name of the profile group to search for" } }, "required": [ "profile_group_name" ], "additionalProperties": false }, "searchProfileGroupsResponse": { "type": "object", "description": "Standard envelope returned by this endpoint on success.", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true for a 2xx response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Profile group id. Same value as profile_group_id on the list endpoint." }, "name": { "type": "string", "description": "Profile group display name." }, "type": { "type": "string", "description": "Group type, for example brand." }, "timezone": { "type": "string", "description": "IANA timezone for the group. Empty string when unset." }, "connect_url": { "type": "string", "description": "URL to connect additional social profiles into this group." } }, "required": [ "id", "name", "type", "timezone", "connect_url" ], "additionalProperties": false }, "description": "Profile groups whose name matches the search string." } }, "required": [ "ok", "data" ] }, "setAutomationStatusRequest": { "type": "object", "properties": { "automation_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Automation ids (24-char hex) to update. Use the `POST /v2/automations/search` endpoint to discover ids." }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ], "description": "New status: active (set live), paused, or deleted (soft delete)." } }, "required": [ "automation_ids", "status" ], "additionalProperties": false }, "updateMediaRequest": { "type": "object", "properties": { "media_id": { "type": "string", "minLength": 1, "description": "The id of the library media item to update — the \"media_gid\" value from a the `POST /v2/media/search` endpoint library result. Required. Never guess this; use the `POST /v2/media/search` endpoint to obtain it." }, "title": { "type": "string", "description": "New title/name for the media. Omit to leave unchanged." }, "description": { "type": "string", "description": "New description for the media. Omit to leave unchanged." }, "alt_text": { "type": "string", "description": "New accessibility alt text. Applies to images only (ignored for video/document/folder). Omit to leave unchanged." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Labels to ADD to the media (additive — existing labels are kept). Omit to leave labels unchanged." }, "labels_to_remove": { "type": "array", "items": { "type": "string" }, "description": "Labels to REMOVE from the media. Labels not currently on the item are ignored. Omit to leave labels unchanged." }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Custom cover IMAGE url for a video. Same as the media library thumbnail update, so it must be a Vista Social media url — use the url of an image returned by the `POST /v2/media/search` endpoint, not an external link. Omit to leave unchanged." }, "thumb_offset": { "type": "number", "minimum": 0, "description": "Video frame offset in seconds to use as the thumbnail. Same as media library thumb_offset. When sent with thumbnail_url, the image wins and this value is only recorded. Omit to leave unchanged." } }, "required": [ "media_id" ], "additionalProperties": false }, "updateProfileGroupRequest": { "type": "object", "properties": { "profile_group_id": { "type": "string", "description": "The profile group ID to update. Required." }, "name": { "type": "string", "description": "New name for the profile group." }, "timezone": { "type": "string", "description": "Exact timezone value from the `POST /v2/timezones/list` endpoint. Before setting, call the `POST /v2/timezones/list` endpoint and match the user input against the list. If no exact match is found, ask the user to confirm the intended timezone before proceeding." }, "brand_voice": { "type": "string", "maxLength": 2000, "description": "Brand voice instructions for content written for this group. Maximum 2,000 characters. Pass empty string to clear." }, "brand_safety_policy": { "type": "string", "description": "Compliance policy text that all outbound content must satisfy before publishing. Pass empty string to clear. Requires a plan that supports brand safety & compliance." }, "brand_safety_active": { "type": "boolean", "description": "Set true to enforce compliance checking, false to disable enforcement while keeping the policy saved. Requires a plan that supports brand safety & compliance." }, "publish_now_delay": { "type": "integer", "minimum": 0, "maximum": 59, "description": "Minutes of delay before publish-now posts go live (0-59)." }, "publish_killswitch": { "type": "boolean", "description": "Set true to disable all publishing for this group, false to re-enable." }, "max_users": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Maximum number of users allowed in the group (1-1000). Use 0 for no limit." }, "max_profiles": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Maximum number of profiles allowed in the group (1-1000). Use 0 for no limit." }, "blocked_networks": { "type": "array", "items": { "type": "string" }, "description": "Social network codes that cannot be connected to this group (for example [\"facebook\",\"tiktok\"]). Replaces the current list. Use the `POST /v2/networks/list` endpoint for valid codes. Pass an empty array to remove all restrictions." }, "shortener": { "type": "boolean", "description": "Set true to enable link shortening for this group, false to disable it." }, "ai_report_summary": { "type": "boolean", "description": "Set true to enable AI report summary, false to disable it." }, "ai_conversation_summary": { "type": "boolean", "description": "Set true to enable AI conversation summary, false to disable it." }, "ai_media_semantic_analysis": { "type": "boolean", "description": "Set true to enable AI media semantic analysis, false to disable it." }, "ai_image_generation": { "type": "boolean", "description": "Set true to enable AI image generation, false to disable it." }, "ai_video_generation": { "type": "boolean", "description": "Set true to enable AI video generation, false to disable it." }, "ai_caption_generator": { "type": "boolean", "description": "Set true to enable AI caption generator, false to disable it." }, "ai_idea_generator": { "type": "boolean", "description": "Set true to enable AI idea generator, false to disable it." }, "ai_smart_publishing": { "type": "boolean", "description": "Set true to enable AI smart publishing, false to disable it." }, "ai_sentiment_analysis": { "type": "boolean", "description": "Set true to enable AI sentiment analysis, false to disable it." } }, "required": [ "profile_group_id" ], "additionalProperties": false }, "updateTaskChecklistItemRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The Vista Work task id that owns the checklist (from the `POST /v2/tasks/get` endpoint)." }, "checklist_item_id": { "type": "string", "description": "Checklist row id (from the `POST /v2/tasks/get` endpoint.subtasks[].id)." }, "title": { "type": "string", "description": "New checklist item title." }, "done": { "type": "boolean", "description": "Mark the checklist row complete (true) or incomplete (false)." }, "assignee_user_id": { "type": "string", "description": "Assignee for this checklist row. Each entry is a user_gid (from the `POST /v2/users/list` endpoint or a project's members), an email, a full name, or \"me\" (the caller). Resolved against the project group: a name/email that matches nobody is rejected, and a user_gid that is not a member of that group is SKIPPED while the call still succeeds (the response says which ids were skipped). So resolve people with the `POST /v2/users/list` endpoint profile_group_id= rather than from the whole account roster. Pass an empty string to clear." }, "due_date": { "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2})?)?$", "description": "Due date for this checklist row. Format as YYYY-MM-DD, or YYYY-MM-DD HH:MM for a specific time. Pass an empty string to clear." }, "order": { "type": "number", "description": "Manual sort order among checklist rows." } }, "required": [ "task_id", "checklist_item_id" ], "additionalProperties": false }, "updateTaskCommentRequest": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The Vista Work task id that owns the comment (from the `POST /v2/tasks/get` endpoint)." }, "comment_id": { "type": "string", "description": "Comment id to edit (from the `POST /v2/tasks/get` endpoint.comments[].id)." }, "message": { "type": "string", "description": "Replacement comment text. Supports @[Name](user_gid) mentions." } }, "required": [ "task_id", "comment_id", "message" ], "additionalProperties": false }, "updateTrendListenerRequest": { "type": "object", "properties": { "listener_gid": { "type": "string", "minLength": 1, "description": "Listener _id from the `POST /v2/trend-listeners/list` endpoint." }, "add_keywords": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "Keywords to add as new top-level OR groups in included_conditions." }, "remove_keywords": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "Keywords to remove from included_conditions (matched by main_value)." }, "enabled": { "type": "boolean", "description": "Soft-pause / resume. true = active, false = paused." }, "notify": { "type": "boolean", "description": "Toggle the notification preference for this listener." } }, "required": [ "listener_gid" ], "additionalProperties": false }, "whoamiRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "whoamiResponse": { "type": "object", "description": "Standard envelope returned by this endpoint on success.", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true for a 2xx response." }, "data": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the API-key owner. Empty string when first and last name are unset." }, "email": { "type": "string", "description": "Email of the API-key owner." } }, "required": [ "name", "email" ], "additionalProperties": false } }, "required": [ "ok", "data" ] } } } }