GoodLeads Agents API

openapi: 3.2.0
info:
  title: Formation GTM Agents API
  description: GoodLeads Formation Data Platform — scored, enriched, campaign-ready leads.
  version: 0.1.0
tags:
- name: Agents
paths:
  /api/v1/agents:
    get:
      tags:
      - Agents
      summary: List Agent Tiles
      description: 'List all agent tiles with their current narratives.


        LIVE tiles include cached narrative headlines. LAUNCH tiles include

        their greeting text. The grid frontend calls this on load and

        after SSE events to refresh affected tiles.'
      operationId: list_agent_tiles_api_v1_agents_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/v1/agents/{agent_id}/narrative:
    get:
      tags:
      - Agents
      summary: Get Tile Narrative
      description: 'Get the narrative for a LIVE agent tile.


        Always calls generate() which uses hash-based caching internally —

        if data hasn''t changed, returns the cached narrative; if data changed,

        generates a fresh one.'
      operationId: get_tile_narrative_api_v1_agents__agent_id__narrative_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agents/{agent_id}/chat:
    post:
      tags:
      - Agents
      summary: Agent Chat
      description: 'Handle a conversational turn with a LAUNCH agent.


        Accepts the operator''s message and conversation history.

        Routes to the appropriate agent service based on agent_id.

        Returns a natural-language response with optional follow-up chips.'
      operationId: agent_chat_api_v1_agents__agent_id__chat_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agents/{agent_id}/config:
    put:
      tags:
      - Agents
      summary: Update Tile Config
      description: Update tile settings (position, enabled, size).
      operationId: update_tile_config_api_v1_agents__agent_id__config_put
      security:
      - APIKeyHeader: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TileConfigUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TileConfigUpdate:
      properties:
        position:
          anyOf:
          - type: integer
          - type: 'null'
          title: Position
        enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enabled
        size:
          anyOf:
          - type: string
          - type: 'null'
          title: Size
      type: object
      title: TileConfigUpdate
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ChatRequest:
      properties:
        message:
          type: string
          title: Message
        context:
          additionalProperties: true
          type: object
          title: Context
          default: {}
      type: object
      required:
      - message
      title: ChatRequest
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key