CatchIntent Health API

openapi: 3.2.0
info:
  title: CatchIntent Agent Discovery Health API
  version: 2.0.0
  description: Public discovery metadata for CatchIntent — the intent layer for B2B outbound. The executable API is the MCP Streamable HTTP endpoint at https://engine.catchintent.com/mcp. Tools cover LinkedIn-first agents, leads, outreach engagements, workspace usage, and brand/product context.
servers:
- url: https://engine.catchintent.com
  description: CatchIntent API and MCP origin
- url: https://catchintent.com
  description: CatchIntent marketing, documentation, and discovery origin
tags:
- name: Health
  description: Service health checks.
paths:
  /v1/healthy:
    get:
      tags:
      - Health
      operationId: getHealth
      summary: Get CatchIntent API health
      responses:
        '200':
          description: Health check response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    examples:
                    - ok
                  info:
                    type: object
                  error:
                    type: object
                  details:
                    type: object
                additionalProperties: true
components:
  securitySchemes:
    mcpOAuth:
      type: oauth2
      description: OAuth 2.1 with PKCE. Discover endpoints from https://engine.catchintent.com/.well-known/oauth-authorization-server. Request only the scopes needed for the MCP tools being called.
      flows:
        authorizationCode:
          authorizationUrl: https://engine.catchintent.com/mcp/authorize
          tokenUrl: https://engine.catchintent.com/mcp/token
          scopes:
            read:agents: Read agents via agent_list, agent_get, agent_runs.
            write:agents: Create, update, and change status of agents via agent_create, agent_update, agent_set_status.
            read:leads: Read leads via lead_search, lead_get.
            write:leads: Update lead status, trigger enrichment, and draft outreach via lead_update_status, lead_enrich, lead_draft_outreach.
            read:outreach: Read outreach engagements and unified inbox via engagement_list, engagement_get, inbox_list.
            write:outreach: Manage engagement lifecycle via engagement_enroll, engagement_reassign, engagement_pause, engagement_resume, engagement_mark_replied, engagement_exit.
            read:workspace: Read workspace usage, ICP options, and product/brand context.
            write:workspace: Create, update, and delete products (brands).
            write:crm: Push qualified leads to connected CRMs via lead_push_to_crm.
x-mcp-tools:
  agent_list:
    scope: read:agents
    role: member
    description: List all agents in the workspace, filterable by productId or signalType.
  agent_get:
    scope: read:agents
    role: member
    description: 'Full details for one agent: status, targeting, signals, lead count, latest run.'
  agent_create:
    scope: write:agents
    role: admin
    planRequirement: Workspace agent limits apply.
    description: Create an agent with signals and targeting (icp, competitors, keywords, influencers).
  agent_update:
    scope: write:agents
    role: admin
    description: Partial update to an agent. Pass signals[] to replace the full signal set.
  agent_set_status:
    scope: write:agents
    role: admin
    description: Activate, pause, archive, unarchive, or start (immediate run for LinkedIn agents).
  agent_runs:
    scope: read:agents
    role: member
    description: Paginated run history per agent.
  lead_search:
    scope: read:leads
    role: member
    description: Search leads in the workspace. Filter by warmth, status, agent, source platform, or text.
  lead_get:
    scope: read:leads
    role: member
    description: 'Full lead details: profile, discovery context, warmth, status, source.'
  lead_update_status:
    scope: write:leads
    role: member
    description: Move a lead through the triage funnel. PUSHED is irreversible.
  lead_enrich:
    scope: write:leads
    role: member
    description: Trigger LinkedIn profile enrichment via Apify (idempotent).
  lead_draft_outreach:
    scope: write:leads
    role: member
    planRequirement: Workspace plan must have AI drafting enabled.
    description: Draft a personalised opener for a lead using discovery context and brand voice. Read-only — no send.
  lead_push_to_crm:
    scope: write:crm
    role: admin
    planRequirement: Workspace plan must include CRM and an integration must be connected.
    description: Push leads to HubSpot, Close, Pipedrive, or Zoho.
  engagement_list:
    scope: read:outreach
    role: member
    description: List outreach engagements. Filter by state or owner.
  engagement_get:
    scope: read:outreach
    role: member
    description: Full details for one engagement.
  engagement_enroll:
    scope: write:outreach
    role: member
    description: Enroll a lead into outreach. The current MCP user becomes the owner.
  engagement_reassign:
    scope: write:outreach
    role: admin
    description: Transfer an engagement to another workspace user.
  engagement_pause:
    scope: write:outreach
    role: member
    description: Pause an engagement, optionally until a date.
  engagement_resume:
    scope: write:outreach
    role: member
    description: Resume a paused engagement.
  engagement_mark_replied:
    scope: write:outreach
    role: member
    description: Mark REPLIED when the lead messaged back outside the product.
  engagement_exit:
    scope: write:outreach
    role: member
    description: 'Terminal exit. Reasons: meeting_booked, opt_out, manual, completed.'
  inbox_list:
    scope: read:outreach
    role: member
    description: Workspace-wide unified outreach inbox for one product.
  workspace_usage:
    scope: read:workspace
    role: member
    description: Current workspace usage vs plan limits.
  workspace_icp_options:
    scope: read:workspace
    role: member
    description: Valid options for ICP fields. Call before product_update or agent_create.
  product_list:
    scope: read:workspace
    role: member
    description: List every product/brand tracked by this workspace.
  product_get:
    scope: read:workspace
    role: member
    description: 'Full brand profile: name, description, domain, keywords, competitors, ICP, voice, offer.'
  product_create:
    scope: write:workspace
    role: admin
    planRequirement: Workspace product limits apply.
    description: Create a new product/brand.
  product_update:
    scope: write:workspace
    role: admin
    description: Update product fields. ICP labels resolved strictly to canonical IDs.
  product_delete:
    scope: write:workspace
    role: admin
    description: Delete a product if it is not the only one and no resources still reference it.