CatchIntent OAuth API

openapi: 3.2.0
info:
  title: CatchIntent Agent Discovery OAuth 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: OAuth
  description: OAuth 2.1 discovery for MCP authentication.
paths:
  /.well-known/oauth-protected-resource:
    get:
      tags:
      - OAuth
      operationId: getOAuthProtectedResourceMetadata
      summary: Get OAuth protected resource metadata
      description: Returns RFC 9728 protected resource metadata for the MCP endpoint.
      responses:
        '200':
          description: OAuth protected resource metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProtectedResourceMetadata'
              example:
                resource: https://catchintent.com
                authorization_servers:
                - https://engine.catchintent.com
                scopes_supported:
                - read:agents
                - write:agents
                - read:leads
                - write:leads
                - read:outreach
                - write:outreach
                - read:workspace
                - write:workspace
                - write:crm
  /.well-known/oauth-protected-resource/mcp:
    get:
      tags:
      - OAuth
      operationId: getOAuthProtectedResourceMetadataForMcp
      summary: Get MCP path-qualified OAuth protected resource metadata
      description: Path-qualified alias for clients that discover protected resource metadata relative to /mcp.
      responses:
        '200':
          description: OAuth protected resource metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProtectedResourceMetadata'
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - OAuth
      operationId: getOAuthAuthorizationServerMetadata
      summary: Get OAuth authorization server metadata
      description: Returns OAuth 2.1 authorization server metadata for MCP authentication.
      responses:
        '200':
          description: OAuth authorization server metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthAuthorizationServerMetadata'
              example:
                issuer: https://engine.catchintent.com
                authorization_endpoint: https://engine.catchintent.com/mcp/authorize
                token_endpoint: https://engine.catchintent.com/mcp/token
                registration_endpoint: https://engine.catchintent.com/mcp/register
                revocation_endpoint: https://engine.catchintent.com/mcp/revoke
                protected_resources:
                - https://engine.catchintent.com/mcp
                response_types_supported:
                - code
                grant_types_supported:
                - authorization_code
                - refresh_token
                token_endpoint_auth_methods_supported:
                - none
                code_challenge_methods_supported:
                - S256
                scopes_supported:
                - read:agents
                - write:agents
                - read:leads
                - write:leads
                - read:outreach
                - write:outreach
                - read:workspace
                - write:workspace
                - write:crm
  /.well-known/oauth-authorization-server/mcp:
    get:
      tags:
      - OAuth
      operationId: getOAuthAuthorizationServerMetadataForMcp
      summary: Get MCP path-qualified OAuth authorization server metadata
      description: Path-qualified alias for clients that discover authorization server metadata relative to /mcp.
      responses:
        '200':
          description: OAuth authorization server metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthAuthorizationServerMetadata'
components:
  schemas:
    OAuthAuthorizationServerMetadata:
      type: object
      required:
      - issuer
      - authorization_endpoint
      - token_endpoint
      - response_types_supported
      - grant_types_supported
      properties:
        issuer:
          type: string
          format: uri
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        registration_endpoint:
          type: string
          format: uri
        revocation_endpoint:
          type: string
          format: uri
        protected_resources:
          type: array
          items:
            type: string
            format: uri
        response_types_supported:
          type: array
          items:
            type: string
        grant_types_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        code_challenge_methods_supported:
          type: array
          items:
            type: string
        scopes_supported:
          type: array
          items:
            $ref: '#/components/schemas/McpScope'
      additionalProperties: true
    OAuthProtectedResourceMetadata:
      type: object
      required:
      - resource
      - authorization_servers
      - scopes_supported
      properties:
        resource:
          type: string
          format: uri
        authorization_servers:
          type: array
          items:
            type: string
            format: uri
        scopes_supported:
          type: array
          items:
            $ref: '#/components/schemas/McpScope'
      additionalProperties: true
    McpScope:
      type: string
      enum:
      - read:agents
      - write:agents
      - read:leads
      - write:leads
      - read:outreach
      - write:outreach
      - read:workspace
      - write:workspace
      - write:crm
      description: OAuth scopes advertised by the MCP auth server and enforced by the registered MCP tools.
  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.