{"openapi":"3.1.0","info":{"title":"SocialCRM API","description":"HTTP API for SocialCRM brand monitoring, AI visibility analytics, and workflow automation.\nFunction-calling clients should use the unique operationId on each path.\n\nAuthentication:\n- OAuth 2.1 authorization code with scopes socialcrm.read (read brand data and analytics) and socialcrm.write (run workflows, mutate prompt sets, create agents).\n- Bearer API keys (sk_live_...) created self-serve at /settings/api-keys after /auth/signup. Each key is scoped to one company workspace.\n\nErrors are JSON: `{ \"error\": { \"code\", \"message\", \"hint\" } }`.\n\nRelated SocialCRM developer resources: /developers, /mcp, /mcp.json, /llms.txt.","version":"1.1.0","contact":{"name":"SocialCRM developers","url":"https://socialcrm.com/developers","email":"support@socialcrm.com"}},"servers":[{"url":"https://socialcrm.com","description":"SocialCRM production"}],"tags":[{"name":"Read","description":"Read operations. OAuth scope: socialcrm.read."},{"name":"Mutations","description":"Write operations. OAuth scope: socialcrm.write."},{"name":"Public diagnostics","description":"Unauthenticated, rate-limited public diagnostics."}],"paths":{"/api/mcp-app/rest/get_agentic_readiness_report":{"post":{"operationId":"get_agentic_readiness_report","tags":["Read"],"summary":"Get Agentic Readiness report","description":"Read the latest completed public SocialCRM Agentic Readiness report for a URL. This read-only tool does not start a scan and does not require authentication. This public read-only operation does not require authentication. The operation retrieves stored public Agentic Readiness information.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","description":"The public HTTP or HTTPS URL used when the report was created."}},"required":["url"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_agentic_readiness_methodology":{"post":{"operationId":"get_agentic_readiness_methodology","tags":["Read"],"summary":"Get Agentic Readiness methodology","description":"Read the SocialCRM score weights, applicability rules, model version, and limits. This read-only tool does not require authentication. This public read-only operation does not require authentication. The operation retrieves stored public Agentic Readiness information.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_agentic_readiness_developer_docs":{"post":{"operationId":"get_agentic_readiness_developer_docs","tags":["Read"],"summary":"Get Agentic Readiness developer docs","description":"Read the public browser, JSON, Markdown, OpenAPI, and MCP interface paths for Agentic Readiness. This read-only tool does not require authentication. This public read-only operation does not require authentication. The operation retrieves stored public Agentic Readiness information.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_brand_snapshot":{"post":{"operationId":"get_brand_snapshot","tags":["Read"],"summary":"Get Brand Snapshot","description":"✅ PRIMARY tool for a full single-brand report. Renders one consolidated Brand Snapshot — brand profile, competitors, repository assets, AI visibility, mentions, monitoring, and trends — for a single brand. Use this when the user wants \"everything\" or a complete overview of one brand. For just a score use get_ai_visibility_score; for a company-wide roll-up use get_dashboard_overview. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand UUID or exact brand name. Call list_brand_profiles first to get valid IDs if needed."},"repositoryCategory":{"type":"string","description":"Optional repository category filter for the snapshot (for example, \"faq\", \"product\", \"blog\")."},"repositoryLimit":{"type":"number","description":"Maximum number of repository items to include (default: 8, max: 20)."},"mentionsLimit":{"type":"number","description":"Maximum number of recent mentions to include (default: 8, max: 20)."},"mentionsPlatform":{"type":"string","description":"Optional AI platform filter for mentions (for example, \"chatgpt\", \"claude\", \"gemini\", \"perplexity\")."},"metricName":{"type":"string","description":"Metric name for the trend section (default: \"visibilityScore\")."},"metricDays":{"type":"number","description":"Number of trailing days for the trend section (default: 30, max: 90)."}},"required":["brandId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_brand_profile":{"post":{"operationId":"get_brand_profile","tags":["Read"],"summary":"Get Brand Profile","description":"Get the detailed profile for ONE specific brand: industry, website, brand voice, keywords, and target audience. Use this when the user asks about a single brand's setup or details. For a full multi-section report (metrics, mentions, competitors, monitoring) use get_brand_snapshot instead; to see the raw list of brands use list_brand_profiles. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand UUID or exact brand name. Call list_brand_profiles first to get valid IDs."}},"required":["brandId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/list_brand_profiles":{"post":{"operationId":"list_brand_profiles","tags":["Read"],"summary":"List Brand Profiles","description":"✅ START HERE. Primary discovery tool: lists every brand profile in the company. Use this first whenever the user names a brand, asks \"what brands do I have?\", or before any tool that needs a brandId — the IDs returned here are required by get_brand_profile, get_brand_snapshot, get_platform_metrics, and most other tools. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_repository_items":{"post":{"operationId":"get_repository_items","tags":["Read"],"summary":"Get Repository Items","description":"Browse or list the stored content items (blog posts, product pages, FAQs, etc.) in a brand's repository, optionally filtered by category. Use this when the user wants to see what content exists or list a category. When the user has specific keywords to find, use search_repository_items instead. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand UUID or exact brand name. Call list_brand_profiles first to get valid IDs."},"category":{"type":"string","description":"Optional category filter (e.g., \"blog\", \"product\", \"faq\")"},"limit":{"type":"number","description":"Maximum number of items to return (default: 50)"},"offset":{"type":"number","description":"Number of items to skip for pagination (default: 0)"}},"required":["brandId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/search_repository_items":{"post":{"operationId":"search_repository_items","tags":["Read"],"summary":"Search Repository Items","description":"Search a brand's repository for content items whose title or body matches a keyword or phrase. Use this when the user is looking for something specific (\"find our pages about brake service\"). To browse everything or filter only by category, use get_repository_items. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand UUID or exact brand name. Call list_brand_profiles first to get valid IDs."},"query":{"type":"string","description":"Search query to match against titles and content"},"limit":{"type":"number","description":"Maximum number of items to return (default: 20)"},"offset":{"type":"number","description":"Number of items to skip for pagination (default: 0)"}},"required":["brandId","query"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_competitors":{"post":{"operationId":"get_competitors","tags":["Read"],"summary":"Get Competitors","description":"List the competitors recorded on a brand profile (names and, when available, sites). Use this when the user asks \"who are my competitors?\". For how the brand actually ranks against them in AI visibility, use get_competitor_rankings instead. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand UUID or exact brand name. Call list_brand_profiles first to get valid IDs."}},"required":["brandId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_platform_metrics":{"post":{"operationId":"get_platform_metrics","tags":["Read"],"summary":"Get Platform Metrics","description":"Get per-engine visibility and mention metrics for one brand, broken out by AI engine (ChatGPT, Claude, Gemini, Perplexity). Use this when the user asks how a brand performs on specific engines or wants an engine-by-engine breakdown. For a single 0-100 headline number use get_ai_visibility_score; for a full report use get_brand_snapshot. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand UUID or exact brand name. Call list_brand_profiles first to get valid IDs."}},"required":["brandId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_brand_mentions":{"post":{"operationId":"get_brand_mentions","tags":["Read"],"summary":"Get Brand Mentions","description":"Get recent mentions and quotes of a brand captured from AI engine checks. Use this when the user asks \"what are the AI engines saying about us?\" or wants recent examples. Pass a platform to focus on one engine. For aggregate scores rather than individual mentions, use get_platform_metrics. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand UUID or exact brand name. Call list_brand_profiles first to get valid IDs."},"limit":{"type":"number","minimum":1,"maximum":100,"description":"Maximum number of mentions to return (default: 50)"},"offset":{"type":"number","minimum":0,"description":"Number of mentions to skip for pagination (default: 0)"},"platform":{"type":"string","description":"Filter to a specific platform (e.g., \"chatgpt\", \"claude\")"}},"required":["brandId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_agent_run_summary":{"post":{"operationId":"get_agent_run_summary","tags":["Read"],"summary":"Get Agent Run Summary","description":"Get execution statistics for an agent instance Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentInstanceId":{"type":"string","description":"The unique identifier of the agent instance"}},"required":["agentInstanceId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_monitoring_results":{"post":{"operationId":"get_monitoring_results","tags":["Read"],"summary":"Get Monitoring Results","description":"Get the latest results and alerts from a brand's monitoring scripts (crawler checks, content-gap and bot-access monitors). Use this when the user asks whether anything is broken or flagged for a brand. For product-wide notifications across all brands, use list_notifications. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand UUID or exact brand name. Call list_brand_profiles first to get valid IDs."}},"required":["brandId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_metric_trend":{"post":{"operationId":"get_metric_trend","tags":["Read"],"summary":"Get Metric Trend","description":"Get a time series of one metric over the last N days for a brand — use this when the user asks how something changed over time, wants a trend, or a chartable history. For the current value only, use get_ai_visibility_score or get_platform_metrics. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand UUID or exact brand name. Call list_brand_profiles first to get valid IDs."},"metricName":{"type":"string","description":"The name of the metric to track (e.g., \"visibilityScore\", \"mentionCount\")"},"days":{"type":"number","description":"Number of days of history to retrieve (default: 30)"}},"required":["brandId","metricName"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_ai_visibility_score":{"post":{"operationId":"get_ai_visibility_score","tags":["Read"],"summary":"Get Ai Visibility Score","description":"Get the AI visibility score for ONE brand — the single headline metric (0-100) for how well it appears across benchmarked engines (ChatGPT, Claude, Gemini, Perplexity). Use this when the user asks \"what's my score?\" for a specific brand. Returns score, change since last calculation, factor breakdown, and issue counts. For the per-engine breakdown use get_platform_metrics; for a company-wide roll-up use get_dashboard_overview. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand UUID or exact brand name. Call list_brand_profiles first to get valid IDs."}},"required":["brandId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_dashboard_overview":{"post":{"operationId":"get_dashboard_overview","tags":["Read"],"summary":"Get Dashboard Overview","description":"✅ Good first call for company-wide status. Returns a high-level roll-up across ALL brands: average visibility score, brand count, open issues (total + critical), and unread notifications. Use this when the user asks \"how are we doing overall?\" (no specific brand). For one brand's score use get_ai_visibility_score; for one brand's full report use get_brand_snapshot. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/list_simulations":{"post":{"operationId":"list_simulations","tags":["Read"],"summary":"List Simulations","description":"List recent AI simulation sessions — probes of how AI platforms answer queries about your brand. Returns platform, brand, mode (visibility = organic probe, readiness = grounded), status, accuracy score, custom query when the run was ad-hoc, and timestamp. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Filter to a specific brand (UUID or exact name). Omit for company-wide history. Call list_brand_profiles to get valid IDs."},"limit":{"type":"number","description":"Maximum number of simulations to return (default: 20, max: 100)"},"offset":{"type":"number","description":"Number of simulations to skip for pagination (default: 0)"}},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_competitor_rankings":{"post":{"operationId":"get_competitor_rankings","tags":["Read"],"summary":"Get Competitor Rankings","description":"Get competitive intelligence rankings showing how your brand compares to competitors in AI visibility. Filterable by brand and platform. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Filter to a specific brand (UUID or exact name). Omit for company-wide view. Call list_brand_profiles to get valid IDs."},"platform":{"type":"string","description":"Filter to a specific AI platform (e.g., \"chatgpt\", \"claude\", \"gemini\", \"perplexity\")"},"limit":{"type":"number","description":"Maximum number of rankings to return (default: 50, max: 100)"}},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/list_notifications":{"post":{"operationId":"list_notifications","tags":["Read"],"summary":"List Notifications","description":"List recent notifications and alerts for the company: bot access events, crawler errors, content gaps, AI mentions, and system alerts. Filter to unread only for actionable items. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number","description":"Maximum number of notifications to return (default: 20, max: 100)"},"offset":{"type":"number","description":"Number of notifications to skip for pagination (default: 0)"},"onlyUnread":{"type":"boolean","description":"If true, only return unread notifications (default: false)"}},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/list_workflows":{"post":{"operationId":"list_workflows","tags":["Read"],"summary":"List Workflows","description":"List all available workflows with their agent counts, credit costs, estimated durations, and whether each is available on the current plan. Call this first to discover which workflows you can run. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_credits":{"post":{"operationId":"get_credits","tags":["Read"],"summary":"Get Credits","description":"Get the current credit balance including available credits, reserved (in-flight) credits, usage this month, monthly limit, and reset date. Check this before running a workflow to ensure sufficient credits. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/run_workflow":{"post":{"operationId":"run_workflow","tags":["Mutations"],"summary":"Run Workflow","description":"Start a workflow run (asynchronous). Returns a runId immediately. The workflow executes in the background — poll get_run_status with the returned runId until status is \"completed\", \"partial_complete\", or \"failed\". Validates plan limits, credit balance, and concurrent run limits before starting. Required OAuth scope: socialcrm.write. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.write"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workflowId":{"type":"string","description":"The workflow ID to run. Use list_workflows to see available IDs (e.g. \"ai_shop_checkup\", \"fix_visibility\", \"competitive_scan\", \"content_refresh\", \"full_service\", \"reputation_shield\")."},"configuration":{"type":"object","description":"Optional configuration passed to the workflow agents.","properties":{"context":{"type":"string","description":"Free-text instructions or context for the workflow agents (e.g., \"Focus on product pages\" or \"Compare against competitor X\")."},"priority":{"type":"string","enum":["low","normal","high"],"description":"Execution priority (default: \"normal\")."},"brandId":{"type":"string","description":"Scope the workflow to a specific brand (UUID or name)."}},"additionalProperties":true}},"required":["workflowId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.write scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_run_status":{"post":{"operationId":"get_run_status","tags":["Read"],"summary":"Get Run Status","description":"Get the full status of a workflow run including overall status, per-agent progress, findings, and error details. Use this to poll a running workflow until completion. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","description":"The run ID returned by run_workflow."}},"required":["runId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/list_workflow_runs":{"post":{"operationId":"list_workflow_runs","tags":["Read"],"summary":"List Workflow Runs","description":"List recent workflow runs with optional filtering by status or workflow type. Returns runs ordered by most recent first. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","running","completed","partial_complete","failed","cancelled"],"description":"Filter runs by status."},"workflowId":{"type":"string","description":"Filter runs by workflow type (e.g. \"ai_shop_checkup\")."},"limit":{"type":"number","description":"Maximum number of runs to return (default 20, max 100)."},"offset":{"type":"number","description":"Number of runs to skip for pagination (default 0)."}},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/cancel_workflow_run":{"post":{"operationId":"cancel_workflow_run","tags":["Mutations"],"summary":"Cancel Workflow Run","description":"Cancel a pending or running workflow run. Only runs with status \"pending\" or \"running\" can be cancelled. Cancelled runs do not consume credits. Required OAuth scope: socialcrm.write. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.write"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","description":"The run ID to cancel."}},"required":["runId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.write scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/list_prompt_sets":{"post":{"operationId":"list_prompt_sets","tags":["Read"],"summary":"List prompt sets","description":"List the company prompt sets available for AI visibility configuration. In the MVP, each active brand is a prompt set so prompts remain tied to a real brand. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/list_tracked_prompts":{"post":{"operationId":"list_tracked_prompts","tags":["Read"],"summary":"List tracked prompts","description":"List the durable prompts in a SocialCRM prompt set, including whether each prompt is enabled in stored configuration. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"promptSetId":{"type":"string","description":"The prompt set ID returned by list_prompt_sets."}},"required":["promptSetId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/add_prompts_to_set":{"post":{"operationId":"add_prompts_to_set","tags":["Mutations"],"summary":"Add prompts to a set","description":"Add one or more durable custom prompts to an existing SocialCRM prompt set. Exact duplicate prompt text is skipped so retries are safe. Required OAuth scope: socialcrm.write. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.write"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"promptSetId":{"type":"string","description":"The prompt set ID returned by list_prompt_sets."},"prompts":{"type":"array","minItems":1,"maxItems":20,"description":"Prompts to add to the stored set.","items":{"type":"object","properties":{"name":{"type":"string","description":"A short, recognizable name for the prompt."},"prompt":{"type":"string","description":"The complete prompt text that SocialCRM should track."},"enabled":{"type":"boolean","description":"Whether the stored prompt should be enabled immediately. Defaults to true."}},"required":["name","prompt"]}}},"required":["promptSetId","prompts"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.write scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/list_reusable_agents":{"post":{"operationId":"list_reusable_agents","tags":["Read"],"summary":"List reusable agents","description":"List reusable SocialCRM agent instances for the current company, including their specialist archetype, status, assigned brands, and runtime configuration. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/create_reusable_agent":{"post":{"operationId":"create_reusable_agent","tags":["Mutations"],"summary":"Create a reusable agent","description":"Create a reusable SocialCRM agent from a supported marketing specialist archetype. The instructions, provider settings, and brand assignments are persisted for later runs and team reuse. Required OAuth scope: socialcrm.write. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.write"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Team-visible name for the reusable agent."},"archetype":{"type":"string","enum":["brand_monitor","content_optimizer","tech_manager","market_analyzer","response_coordinator","ai_simulator","strategist","writer","optimizer"],"description":"The specialist runtime and guardrail profile to build on."},"instructions":{"type":"string","description":"Persistent system instructions defining the agent objective, method, and expected output."},"brandIds":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Optional company brand IDs assigned to this agent."},"provider":{"type":"string","enum":["claude","openai","gemini"],"description":"Model provider. Defaults to Claude."},"model":{"type":"string","description":"Optional model override for the selected provider."},"tools":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["WebSearch","WebFetch"]},"description":"Optional external tools. Tenant-scoped SocialCRM data tools are enabled automatically."}},"required":["name","archetype","instructions"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.write scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/run_reusable_agent":{"post":{"operationId":"run_reusable_agent","tags":["Mutations"],"summary":"Run a reusable agent","description":"Queue a run for a reusable SocialCRM agent. Returns a stable run ID that can be polled with get_agent_run_status. Required OAuth scope: socialcrm.write. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.write"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","description":"The reusable agent ID returned by create_reusable_agent or list_reusable_agents."},"brandId":{"type":"string","description":"Optional company brand ID for this run."},"instructions":{"type":"string","description":"Optional run-specific instructions appended to the saved agent instructions."}},"required":["agentId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.write scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/mcp-app/rest/get_agent_run_status":{"post":{"operationId":"get_agent_run_status","tags":["Read"],"summary":"Get agent run status","description":"Get the current status and persisted result for a reusable-agent run in the current company. Required OAuth scope: socialcrm.read. API keys (sk_live_...) are company-scoped to the workspace that created the key.","security":[{"OAuth2":["socialcrm.read"]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","description":"The run ID returned by run_reusable_agent."}},"required":["runId"]}}}},"responses":{"200":{"description":"Successful tool execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid request or tool error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INVALID_PARAMS","message":"The request body did not match the tool schema.","hint":"Compare your JSON with the requestBody schema for this operationId."}}}}},"401":{"description":"Unauthorized — missing, invalid, or under-scoped credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid SocialCRM API key or OAuth access token is required.","hint":"Send Authorization: Bearer <token>. OAuth clients need the socialcrm.read scope."}}}}},"404":{"description":"Unknown tool or resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"No SocialCRM API route matches this path.","hint":"See /openapi.json for published operationIds."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for this key.","hint":"Wait for Retry-After seconds, then retry. General limit is 60 requests per minute."}}}}}}}},"/api/skills/ai-readiness":{"post":{"operationId":"scan_agent_readiness","tags":["Public diagnostics"],"summary":"Scan a public website for agent readiness","description":"Requests public website surfaces and returns an evidence-backed readiness report. The scanner blocks private and credential-bearing URLs. No authentication is required.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public HTTP or HTTPS website URL to scan."}}}}}},"responses":{"200":{"description":"Point-in-time public agent-readiness report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentReadinessReport"}}}},"400":{"description":"Invalid JSON, missing URL, or non-public target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Public scan rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"The public site scan did not complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/is-agentic/scans":{"post":{"operationId":"create_agentic_readiness_scan","tags":["Public diagnostics"],"summary":"Create or reuse a stored Agentic Readiness scan","description":"Creates a public scan job for a public HTTP or HTTPS URL. Returns 202 with a stable report URL and poll URL. Fresh completed reports can return immediately.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"A fresh completed report already exists.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"The scan is queued or running.","content":{"application/json":{"schema":{"type":"object","required":["scan","cacheStatus"],"properties":{"scan":{"$ref":"#/components/schemas/AgenticScan"},"cacheStatus":{"type":"string"}}}}}},"400":{"description":"Invalid, private, or credential-bearing URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Scan rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/is-agentic/scans/{token}":{"get":{"operationId":"get_agentic_readiness_scan","tags":["Public diagnostics"],"summary":"Read a stored scan job and completed report","description":"Returns the current job state. Poll this operation after the create operation returns 202.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque public report token returned by the create operation.","schema":{"type":"string","minLength":20,"maxLength":80}}],"responses":{"200":{"description":"Current scan job and report state.","content":{"application/json":{"schema":{"type":"object","required":["scan"],"properties":{"scan":{"$ref":"#/components/schemas/AgenticScan"}}}}}},"404":{"description":"Unknown scan token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"The public report expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/is-agentic/scans/{token}/rescan":{"post":{"operationId":"rescan_agentic_readiness","tags":["Public diagnostics"],"summary":"Rescan a stored public report","description":"Queues replacement evidence without changing the stable report URL. The previous completed report remains available until replacement completes.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque public report token returned by the create operation.","schema":{"type":"string","minLength":20,"maxLength":80}}],"responses":{"202":{"description":"The rescan is queued or already running.","content":{"application/json":{"schema":{"type":"object","required":["scan"],"properties":{"scan":{"$ref":"#/components/schemas/AgenticScan"}}}}}},"404":{"description":"Unknown scan token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rescan rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/is-agentic/scans/{token}/audit":{"get":{"operationId":"get_agentic_readiness_audit","tags":["Public diagnostics"],"summary":"Read the raw stored readiness audit","description":"Returns the complete stored report JSON for a completed scan.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Opaque public report token returned by the create operation.","schema":{"type":"string","minLength":20,"maxLength":80}}],"responses":{"200":{"description":"Complete stored audit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticReadinessReport"}}}},"404":{"description":"Unknown scan token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The report is not complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/agent-readiness/report":{"get":{"operationId":"get_latest_agentic_readiness_report","tags":["Public diagnostics"],"summary":"Read the latest completed report for a public URL","description":"Read-only versioned report API. This operation does not start or mutate a scan.","security":[],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"Public target URL used when the report was created."}],"responses":{"200":{"description":"Latest completed stored report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticScan"}}}},"400":{"description":"Invalid public URL.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"No completed report exists.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Report read rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"ApiError":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."},"hint":{"type":"string","description":"What the caller should do next."}}}}},"ToolResult":{"type":"object","description":"Successful SocialCRM tool result. Read tools return structured JSON; some connectors wrap output in an MCP content array.","additionalProperties":true,"properties":{"content":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}}}},"isError":{"type":"boolean"},"structuredContent":{"type":"object","additionalProperties":true}}},"AgentReadinessReport":{"type":"object","additionalProperties":true,"required":["modelVersion","score","grade","summary","url","host","analyzedAt","categories","checks","prioritizedFixes","limitations"],"properties":{"modelVersion":{"type":"string"},"score":{"type":"integer","minimum":0,"maximum":100},"grade":{"type":"string","enum":["Agent-ready","Ready with gaps","Needs work","Agent blocked"]},"summary":{"type":"string"},"url":{"type":"string","format":"uri"},"host":{"type":"string"},"analyzedAt":{"type":"string","format":"date-time"},"categories":{"type":"array","items":{"type":"object","additionalProperties":true,"required":["id","label","score","maxScore","passed","applicable"],"properties":{"id":{"type":"string","enum":["essential","recommended"]},"label":{"type":"string"},"score":{"type":"number","minimum":0},"maxScore":{"type":"number","minimum":0},"passed":{"type":"integer","minimum":0},"applicable":{"type":"integer","minimum":0}}}},"checks":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","title","tier","status","weight","evidence","recommendation"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"tier":{"type":"string","enum":["essential","recommended"]},"status":{"type":"string","enum":["passed","partial","failed","not_evaluated"]},"weight":{"type":"number","minimum":0},"evidence":{"type":"string"},"recommendation":{"type":"string"},"observedUrl":{"type":"string","format":"uri"},"surface":{"type":"string","enum":["website","api","authentication","mcp"]},"evidenceSource":{"type":"string"}}}},"prioritizedFixes":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}}}},"AgenticReadinessReport":{"allOf":[{"$ref":"#/components/schemas/AgentReadinessReport"},{"type":"object","required":["scoreBeforeBonus","bonusScore","surfaces","criticalAccess","taskObservation","bonusSignals","maturePassed","matureApplicable"],"properties":{"scoreBeforeBonus":{"type":"number","minimum":0,"maximum":100},"bonusScore":{"type":"number","minimum":0,"maximum":5},"surfaces":{"type":"array","items":{"type":"object","additionalProperties":true}},"criticalAccess":{"type":"array","items":{"type":"object","additionalProperties":true}},"taskObservation":{"type":"object","additionalProperties":true},"bonusSignals":{"type":"array","items":{"type":"object","additionalProperties":true}},"maturePassed":{"type":"integer","minimum":0},"matureApplicable":{"type":"integer","minimum":0}}}]},"AgenticScan":{"type":"object","additionalProperties":false,"required":["publicToken","targetUrl","targetHost","status","modelVersion","history","attemptCount","retry_after_ms","createdAt","expiresAt","updatedAt","persistence","links"],"properties":{"publicToken":{"type":"string","description":"Opaque stable public report token."},"targetUrl":{"type":"string","format":"uri"},"targetHost":{"type":"string"},"status":{"type":"string","enum":["queued","running","complete","failed"]},"modelVersion":{"type":"string"},"score":{"type":["integer","null"],"minimum":0,"maximum":100},"grade":{"type":["string","null"]},"report":{"anyOf":[{"$ref":"#/components/schemas/AgenticReadinessReport"},{"type":"null"}]},"history":{"type":"array","items":{"type":"object","required":["score","grade","analyzedAt","modelVersion"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"grade":{"type":"string"},"analyzedAt":{"type":"string","format":"date-time"},"modelVersion":{"type":"string"}}}},"attemptCount":{"type":"integer","minimum":0},"error":{"type":["object","null"],"additionalProperties":true},"retry_after_ms":{"type":"integer","minimum":250},"createdAt":{"type":"string","format":"date-time"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"persistence":{"type":"string","enum":["durable","ephemeral"]},"links":{"type":"object","additionalProperties":false,"required":["report","status","audit","markdown","rescan"],"properties":{"report":{"type":"string","format":"uri"},"status":{"type":"string","format":"uri"},"audit":{"type":"string","format":"uri"},"markdown":{"type":"string","format":"uri"},"rescan":{"type":"string","format":"uri"}}}}},"ProblemDetails":{"type":"object","additionalProperties":false,"required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string"},"resolution":{"type":"string"},"retry_after_ms":{"type":"integer","minimum":0}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"SocialCRM API key (sk_live_...). Keys are company-scoped to the issuing workspace and inherit that workspace's data boundary. Create keys self-serve at /settings/api-keys."},"OAuth2":{"type":"oauth2","description":"SocialCRM OAuth 2.1 for ChatGPT, Claude, and other connectors. Request only the scopes each tool needs.","flows":{"authorizationCode":{"authorizationUrl":"https://socialcrm.com/api/oauth/authorize","tokenUrl":"https://socialcrm.com/api/oauth/token","scopes":{"socialcrm.read":"Read SocialCRM brand profiles, repository items, mentions, metrics, and run status.","socialcrm.write":"Run workflows, cancel runs, add prompts, and create or run reusable agents. Includes read access."}}}}}}}