CatchIntent Discovery API

openapi: 3.2.0
info:
  title: CatchIntent Agent Discovery 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: Discovery
  description: Agent-readable discovery resources served from the marketing origin.
paths:
  /.well-known/api-catalog:
    get:
      tags:
      - Discovery
      operationId: getApiCatalog
      summary: Get the CatchIntent API catalog
      description: Returns the RFC 9727 API catalog as an RFC 9264 linkset document.
      responses:
        '200':
          description: RFC 9727 API catalog linkset
          content:
            application/linkset+json:
              schema:
                $ref: '#/components/schemas/ApiCatalog'
  /.well-known/mcp/server-card.json:
    get:
      tags:
      - Discovery
      operationId: getMcpServerCard
      summary: Get the CatchIntent MCP server card
      description: Returns the MCP server card used by agents to discover transport, auth, and tool capabilities.
      responses:
        '200':
          description: MCP server card
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerCard'
  /.well-known/agent-skills/index.json:
    get:
      tags:
      - Discovery
      operationId: getAgentSkillsIndex
      summary: Get the CatchIntent agent skills index
      description: Returns the agent skills discovery index with a SHA-256 digest for each skill artifact.
      responses:
        '200':
          description: Agent skills index
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSkillsIndex'
components:
  schemas:
    LinksetRelation:
      type: array
      items:
        type: object
        required:
        - href
        properties:
          href:
            type: string
            format: uri
          type:
            type: string
          title:
            type: string
        additionalProperties: true
    AgentSkillsIndex:
      type: object
      required:
      - $schema
      - skills
      properties:
        $schema:
          type: string
          format: uri
        skills:
          type: array
          items:
            type: object
            required:
            - name
            - type
            - description
            - url
            - digest
            properties:
              name:
                type: string
              type:
                type: string
                enum:
                - skill-md
                - archive
              description:
                type: string
              url:
                type: string
              digest:
                type: string
                pattern: ^sha256:[a-f0-9]{64}$
            additionalProperties: true
      additionalProperties: true
    ApiCatalog:
      type: object
      required:
      - linkset
      properties:
        linkset:
          type: array
          items:
            type: object
            required:
            - anchor
            properties:
              anchor:
                type: string
                format: uri
              service-desc:
                $ref: '#/components/schemas/LinksetRelation'
              service-doc:
                $ref: '#/components/schemas/LinksetRelation'
              service-meta:
                $ref: '#/components/schemas/LinksetRelation'
              status:
                $ref: '#/components/schemas/LinksetRelation'
            additionalProperties: true
      additionalProperties: true
    McpToolName:
      type: string
      enum:
      - agent_list
      - agent_get
      - agent_create
      - agent_update
      - agent_set_status
      - agent_runs
      - lead_search
      - lead_get
      - lead_update_status
      - lead_enrich
      - lead_draft_outreach
      - lead_push_to_crm
      - engagement_list
      - engagement_get
      - engagement_enroll
      - engagement_reassign
      - engagement_pause
      - engagement_resume
      - engagement_mark_replied
      - engagement_exit
      - inbox_list
      - workspace_usage
      - workspace_icp_options
      - product_list
      - product_get
      - product_create
      - product_update
      - product_delete
    McpServerCard:
      type: object
      required:
      - serverInfo
      - transport
      - capabilities
      properties:
        serverInfo:
          type: object
          required:
          - name
          - version
          properties:
            name:
              type: string
            version:
              type: string
            description:
              type: string
          additionalProperties: true
        transport:
          type: object
          properties:
            type:
              type: string
              const: streamable-http
            endpoint:
              type: string
              format: uri
            authorization:
              type: object
              additionalProperties: true
          additionalProperties: true
        capabilities:
          type: object
          properties:
            tools:
              type: boolean
            resources:
              type: boolean
            prompts:
              type: boolean
            sampling:
              type: boolean
          additionalProperties: true
        tools:
          type: array
          items:
            $ref: '#/components/schemas/McpToolName'
        documentation:
          type: string
          format: uri
        skills:
          type: string
          format: uri
      additionalProperties: true
  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.