ClawLink Discovery API

openapi: 3.2.0
info:
  title: ClawLink Agent Discovery API
  version: 1.0.0
  summary: Tool discovery and execution for AI agents
  description: 'ClawLink connects AI agents to 100+ external apps (Gmail, Slack, Notion, GitHub, and more) through one hosted account. This document describes the agent-facing surface: tool discovery, tool execution, the MCP endpoint, and the two credential registration flows. How authentication works, including the human-approval requirement, is documented at https://claw-link.dev/auth.md. All other routes on claw-link.dev (dashboard, billing, connect pages) are browser-facing and not part of this API.'
  contact:
    name: ClawLink
    url: https://claw-link.dev
servers:
- url: https://claw-link.dev
security:
- ApiKeyHeader: []
- BearerAuth: []
tags:
- name: Discovery
  description: List, search, and describe the tools available to the authenticated user
paths:
  /api/tools:
    get:
      tags:
      - Discovery
      operationId: listTools
      summary: List available tools
      description: 'Returns a capped page of tools (default 50, max 200), sorted by integration then name. Schemas are not included; call describeTool for the one tool you plan to run. When the list is truncated, the final array entry is a notice object with "name": null describing how many tools were omitted.'
      parameters:
      - name: integration
        in: query
        description: Filter to one integration slug, for example "gmail".
        schema:
          type: string
      - name: limit
        in: query
        description: Page size. Default 50, maximum 200.
        schema:
          type: integer
          minimum: 1
          maximum: 200
      responses:
        '200':
          description: Tool page
          content:
            application/json:
              schema:
                type: object
                required:
                - tools
                - count
                - total
                - truncated
                properties:
                  tools:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tool'
                  count:
                    type: integer
                    description: Number of tools in this page.
                  total:
                    type: integer
                    description: Total tools available to this user.
                  truncated:
                    type: boolean
                  integration:
                    type:
                    - string
                    - 'null'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/tools/search:
    get:
      tags:
      - Discovery
      operationId: searchTools
      summary: Search tools by keyword
      parameters:
      - name: query
        in: query
        required: true
        description: Keyword to match against tool names and descriptions.
        schema:
          type: string
      - name: integration
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Matching tools
          content:
            application/json:
              schema:
                type: object
                required:
                - tools
                - count
                - query
                properties:
                  tools:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tool'
                  count:
                    type: integer
                  query:
                    type: string
                  integration:
                    type:
                    - string
                    - 'null'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/tools/{name}:
    get:
      tags:
      - Discovery
      operationId: describeTool
      summary: Describe one tool, including its input schema
      description: The list and search responses omit input schemas. Call this for the tool you plan to execute; the response includes its hydrated JSON Schema.
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: Tool name as returned by listTools or searchTools.
      responses:
        '200':
          description: Tool description
          content:
            application/json:
              schema:
                type: object
                required:
                - tool
                properties:
                  tool:
                    $ref: '#/components/schemas/Tool'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/mcp/server-card:
    get:
      tags:
      - Discovery
      operationId: getMcpServerCard
      summary: MCP Server Card
      security: []
      description: 'Static pre-connection description of the MCP server (SEP-2127): identity, transport endpoint, and supported protocol versions. Public and unauthenticated, so a client can read it before it holds a key. Primitives (tools, prompts, resources) are deliberately absent because the tool list is per-user; list them at runtime instead. The same document is served at /.well-known/mcp/server-card.json.'
      responses:
        '200':
          description: MCP Server Card
          content:
            application/mcp-server-card+json:
              schema:
                type: object
                required:
                - $schema
                - name
                - version
                - description
                properties:
                  $schema:
                    type: string
                  name:
                    type: string
                  version:
                    type: string
                  description:
                    type: string
                  title:
                    type: string
                  websiteUrl:
                    type: string
                  remotes:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                additionalProperties: true
        '304':
          description: Not modified (matched If-None-Match)
components:
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    Tool:
      type: object
      description: 'A tool the authenticated user can run. List and search responses omit inputSchema; describeTool includes it. A truncation notice entry has "name": null and is not callable.'
      properties:
        integration:
          type:
          - string
          - 'null'
          description: Integration slug, for example "gmail".
        name:
          type:
          - string
          - 'null'
          description: Tool name to pass to executeTool.
        description:
          type: string
        inputSchema:
          type:
          - object
          - 'null'
          description: JSON Schema for the arguments object. Null or a placeholder in list responses; hydrated by describeTool.
          additionalProperties: true
        canonical:
          type: object
          description: 'Canonical summary: integration_id, action, and default connection state.'
          additionalProperties: true
      additionalProperties: true
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-clawlink-api-key
      description: A cllk_live_ API key obtained through one of the registration flows.
    BearerAuth:
      type: http
      scheme: bearer
      description: The same cllk_live_ key as a bearer token. Both header forms are accepted on every authenticated endpoint.
    OAuth2:
      type: oauth2
      description: For remote MCP clients calling /api/mcp. Discovery starts at https://claw-link.dev/.well-known/oauth-protected-resource; client registration follows the authorization server metadata.
      flows:
        authorizationCode:
          authorizationUrl: https://clerk.claw-link.dev/oauth/authorize
          tokenUrl: https://clerk.claw-link.dev/oauth/token
          refreshUrl: https://clerk.claw-link.dev/oauth/token
          scopes:
            openid: Identify the authorizing user
            email: Read the user's email address
            profile: Read basic profile information
externalDocs:
  description: ClawLink documentation
  url: https://docs.claw-link.dev