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 Automotive Agent Readiness report
      description: "Read the latest completed public SocialCRM Automotive Agent Readiness report for a dealer, repair shop, or service website. The report separates technical readiness from applicable vehicle, service, and handoff journeys. 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 Automotive Agent Readiness methodology
      description: "Read the SocialCRM technical and automotive score weights, dealer and repair-shop applicability rules, model versions, 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 Automotive Agent Readiness developer docs
      description: "Read the public browser, JSON, Markdown, OpenAPI, and MCP interface paths for SocialCRM Automotive Agent 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
                      minLength: 1
                      maxLength: 20000
                      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
                      minLength: 1
                      maxLength: 200
                      description: Scope the workflow to a specific brand (UUID or name).
                  additionalProperties: false
              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
                  minimum: 1
                  maximum: 100
                  description: "Maximum number of runs to return (default 20, max 100)."
                offset:
                  type: number
                  minimum: 0
                  maximum: 1000000
                  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. The report includes a core technical score and an applicability-aware automotive overlay when dealer or repair-shop evidence is present. Returns 202 with a stable report URL and poll URL.
      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 stored report wrapped with SocialCRM publisher identity, socialcrm.com HTML URLs, and an iframe embed snippet. The human HTML view lives at /is-agentic/scan/{token}/audit."
      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, wrapped with SocialCRM publisher and embed URLs."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgenticAuditDocument"
        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
            automotive:
              $ref: "#/components/schemas/AutomotiveReadiness"
    AgenticAuditDocument:
      type: object
      additionalProperties: false
      required:
        - publisher
        - embed
        - links
        - scan
        - report
      properties:
        publisher:
          type: object
          additionalProperties: false
          required:
            - name
            - url
            - product
          properties:
            name:
              type: string
            url:
              type: string
              format: uri
            product:
              type: string
              format: uri
        embed:
          type: object
          additionalProperties: false
          required:
            - url
            - page
            - iframe
          properties:
            url:
              type: string
              format: uri
              description: HTML report to iframe on socialcrm.com
            page:
              type: string
              format: uri
              description: HTML audit page that hosts the raw JSON on socialcrm.com
            iframe:
              type: string
        links:
          type: object
          additionalProperties: false
          required:
            - report
            - auditPage
            - status
            - audit
            - markdown
            - rescan
          properties:
            report:
              type: string
              format: uri
            auditPage:
              type: string
              format: uri
            status:
              type: string
              format: uri
            audit:
              type: string
              format: uri
            markdown:
              type: string
              format: uri
            rescan:
              type: string
              format: uri
        scan:
          type: object
          additionalProperties: false
          required:
            - publicToken
            - targetUrl
            - targetHost
            - status
            - expiresAt
          properties:
            publicToken:
              type: string
            targetUrl:
              type: string
              format: uri
            targetHost:
              type: string
            status:
              type: string
            completedAt:
              type:
                - string
                - "null"
              format: date-time
            expiresAt:
              type: string
              format: date-time
        score:
          type:
            - integer
            - "null"
          minimum: 0
          maximum: 100
        grade:
          type:
            - string
            - "null"
        report:
          $ref: "#/components/schemas/AgenticReadinessReport"
    AutomotiveReadiness:
      type: object
      additionalProperties: false
      required:
        - modelVersion
        - applicable
        - score
        - grade
        - summary
        - classification
        - checks
        - journeys
        - prioritizedFixes
        - handoffs
      properties:
        modelVersion:
          type: string
        applicable:
          type: boolean
        score:
          type:
            - integer
            - "null"
          minimum: 0
          maximum: 100
        grade:
          type: string
          enum:
            - Automotive ready
            - Ready with gaps
            - Needs work
            - Blocked
            - Not evaluated
        summary:
          type: string
        classification:
          type: object
          additionalProperties: false
          required:
            - type
            - label
            - confidence
            - evidence
          properties:
            type:
              type: string
              enum:
                - dealer
                - repair_shop
                - dealer_service
                - specialty_service
                - unknown
            label:
              type: string
            confidence:
              type: string
              enum:
                - high
                - moderate
                - low
            evidence:
              type: array
              items:
                type: string
        checks:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - id
              - title
              - journey
              - status
              - weight
              - evidence
              - recommendation
            properties:
              id:
                type: string
              title:
                type: string
              journey:
                type: string
              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
        journeys:
          type: array
          items:
            type: object
            additionalProperties: true
        prioritizedFixes:
          type: array
          items:
            type: string
        handoffs:
          type: array
          items:
            type: object
            additionalProperties: true
    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
            additionalProperties: false
            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
              automotiveScore:
                type:
                  - integer
                  - "null"
                minimum: 0
                maximum: 100
              automotiveProfile:
                type: string
                enum:
                  - dealer
                  - repair_shop
                  - dealer_service
                  - specialty_service
                  - unknown
        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
            - auditPage
            - status
            - audit
            - markdown
            - rescan
          properties:
            report:
              type: string
              format: uri
            auditPage:
              type: string
              format: uri
              description: HTML audit page on socialcrm.com
            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."
