Gojiberry AI Lead source agents API

openapi: 3.2.0
info:
  title: Gojiberry AI - External Lead source agents API
  description: '# Gojiberry AI External API


    This API allows you to programmatically access your Gojiberry AI data and integrate it with your applications.'
  version: '1.0'
  contact: {}
servers: []
tags:
- name: Lead source agents
paths:
  /v1/agent:
    get:
      description: Retrieve all source agents for the authenticated user
      operationId: AgentExternalController_findAll
      parameters:
      - name: x-impersonate-user-id
        in: header
        description: ID of an organization member to act on behalf of. The API key user must be the owner of the organization and the target user must belong to the same organization.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of agents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Agent'
      security:
      - bearer: []
      summary: Get all source agents
      tags:
      - Lead source agents
  /v1/agent/{id}:
    get:
      description: Retrieve a single source agent by ID
      operationId: AgentExternalController_findOne
      parameters:
      - name: x-impersonate-user-id
        in: header
        description: ID of an organization member to act on behalf of. The API key user must be the owner of the organization and the target user must belong to the same organization.
        required: false
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: Agent found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '404':
          description: Agent not found
      security:
      - bearer: []
      summary: Get one source agent
      tags:
      - Lead source agents
    patch:
      description: Update a source agent by ID
      operationId: AgentExternalController_update
      parameters:
      - name: x-impersonate-user-id
        in: header
        description: ID of an organization member to act on behalf of. The API key user must be the owner of the organization and the target user must belong to the same organization.
        required: false
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentDto'
      responses:
        '200':
          description: Agent updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: Invalid payload (e.g. fewer than 4 variables)
        '404':
          description: Agent not found
      security:
      - bearer: []
      summary: Update a source agent
      tags:
      - Lead source agents
  /v1/agent/{id}/logs:
    get:
      description: Retrieve the run logs for one AI Agent. Each log entry corresponds to one signal run and reports how many leads were sourced vs. how many ended up imported into the platform after AI scoring & filtering. Use this to answer questions like "how many leads did this agent create last week?", "which signals are producing the most leads?", or "did any of this agent's signals fail recently?". Optionally narrow the window with dateFrom / dateTo (ISO 8601). Capped at the most recent 100 logs (newest first).
      operationId: AgentExternalController_findLogs
      parameters:
      - name: x-impersonate-user-id
        in: header
        description: ID of an organization member to act on behalf of. The API key user must be the owner of the organization and the target user must belong to the same organization.
        required: false
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: number
      - name: dateFrom
        required: false
        in: query
        description: Start of the time window (ISO 8601, e.g. 2025-04-01T00:00:00Z). Used together with dateTo.
        schema:
          type: string
      - name: dateTo
        required: false
        in: query
        description: End of the time window (ISO 8601). Used together with dateFrom.
        schema:
          type: string
      responses:
        '200':
          description: Up to 100 most recent log entries for the agent (newest first).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentLog'
        '404':
          description: Agent not found
      security:
      - bearer: []
      summary: Get logs for a source agent
      tags:
      - Lead source agents
components:
  schemas:
    UpdateAgentDto:
      type: object
      properties:
        name:
          type: string
          description: Name of the agent
        targetJobTitles:
          description: Target job titles to search for
          type: array
          items:
            type: string
        targetIndustries:
          description: Target industries to search in
          type: array
          items:
            type: string
        targetCompanySizes:
          description: Target company sizes
          type: array
          items:
            type: string
        targetLocations:
          description: Target locations to search in
          type: array
          items:
            type: string
        targetCompanyTypes:
          description: Target company types
          type: array
          items:
            type: string
        additionalCriteria:
          type: string
          description: Additional search criteria or instructions
          deprecated: true
          maxLength: 200
        agentType:
          type: string
          description: 'Type of agent : "autopilot", "lookalike" or "website-visitor"'
        variables:
          description: Agent variables configuration (minimum 4 required)
          type: array
          items:
            $ref: '#/components/schemas/AgentVariableV2Dto'
        ignoredCompanies:
          description: Companies to ignore in search results
          type: array
          items:
            type: string
        mandatoryKeywords:
          description: Keywords that must be present in the profile
          type: array
          items:
            type: string
        listId:
          type: number
          description: ID of the list to associate with this agent
        excludeServiceProviders:
          type: boolean
          description: Exclude service providers from results
        skipIcpFilter:
          type: boolean
          description: Skip ICP (Ideal Customer Profile) filter
        includeOpenToWorkProfiles:
          type: boolean
          description: Include open-to-work profiles in results
        leadWaterfall:
          type: boolean
          description: Enable lead waterfall mode
        paused:
          type: boolean
          description: Whether the agent is paused
        minLeadScore:
          type: number
          description: Minimum lead score threshold (0–1)
        scriptInstalled:
          type: boolean
          description: Whether the visitor tracking script is installed on the website (website-visitor agents)
        maxCreditUsage:
          type: number
          description: Max number of credits per month
    AgentLog:
      type: object
      properties:
        id:
          type: number
          description: Unique identifier of the agent log entry.
        leadsCreated:
          type: number
          description: Number of leads imported into the user platform after the AI scoring & filtering pipeline. These are the qualified leads that ended up on the agent's list and become contacts of the linked outreach campaign.
        totalLeads:
          type: number
          description: Total number of raw leads the agent found from this signal in this run, BEFORE any AI scoring or filtering. Always greater than or equal to leadsCreated.
        errorMessage:
          type:
          - string
          - 'null'
          description: Error message if the run failed for this signal. Null when the run succeeded.
        agentType:
          type:
          - object
          - 'null'
          description: Type of signal the agent ran (e.g. SEARCH_KEYWORD, COMPETITOR_PAGE_URL, RECENT_FUNDING_EVENT). Matches the agent's configured signal types.
        agentKeyword:
          type:
          - string
          - 'null'
          description: The specific signal value used in this run — e.g. the keyword searched, the competitor page URL watched, or the lookalike seed. Lets you see which signal produced which leads.
        userId:
          type: number
          description: Owner user ID.
        agentId:
          type:
          - number
          - 'null'
          description: ID of the agent this log entry belongs to.
        createdAt:
          format: date-time
          type: string
          description: When this log entry was recorded (ISO 8601).
      required:
      - id
      - leadsCreated
      - totalLeads
      - userId
      - createdAt
    Agent:
      type: object
      properties:
        id:
          type: number
          description: Unique identifier
        name:
          type: string
          description: Display name of the agent
        targetJobTitles:
          description: List of target job titles to prospect. Part of the ICP.
          type: array
          items:
            type: string
        targetIndustries:
          description: List of target industries to prospect. Part of the ICP.
          type: array
          items:
            type: string
        targetCompanySizes:
          description: List of target company sizes (e.g. "1-10", "11-50"). Part of the ICP.
          type: array
          items:
            type: string
        targetLocations:
          description: List of target geographic locations. Part of the ICP.
          type: array
          items:
            type: string
        targetCompanyTypes:
          description: List of target company types (e.g. "Public", "Private")
          type: array
          items:
            type: string
        additionalCriteria:
          type:
          - string
          - 'null'
          description: Additional free-text targeting criteria
        variables:
          description: Variables used by the agent to find high intent leads. (Keywords, Competitor Page URL, etc.)
          type:
          - array
          - 'null'
          items:
            type: string
        ignoredCompanies:
          description: Company names to exclude from prospecting. Part of the ICP.
          type:
          - array
          - 'null'
          items:
            type: string
        mandatoryKeywords:
          description: Keywords that must be present in a lead profile to be included
          type:
          - array
          - 'null'
          items:
            type: string
        agentType:
          type: string
          description: 'Type of agent: "autopilot", "lookalike" or "website-visitor"'
          example: autopilot
        scriptInstalled:
          type: boolean
          description: Whether the visitor tracking script is installed on the website (website-visitor agents)
          default: false
        maxCreditUsage:
          type:
          - number
          - 'null'
          description: Max number of credits per month
          example: 200
        lastRun:
          format: date-time
          type:
          - string
          - 'null'
          description: Timestamp of the last agent execution
        paused:
          type: boolean
          description: Whether the agent is paused and will not run on its next scheduled time
          default: false
        excludeServiceProviders:
          type: boolean
          description: Whether to exclude service provider companies from prospecting
          default: false
        skipIcpFilter:
          type: boolean
          description: Whether to skip the ICP (Ideal Customer Profile) filter when sourcing leads
          default: false
        includeOpenToWorkProfiles:
          type: boolean
          description: Whether to include LinkedIn profiles marked as open to work
          default: false
        leadWaterfall:
          type: boolean
          description: Whether to use the lead waterfall strategy (cascade through multiple sources)
          default: true
        minLeadScore:
          type:
          - number
          - 'null'
          description: Minimum lead score threshold (0.00–1.00) required to include a lead
          example: 0.75
        userId:
          type: number
          description: ID of the account (user) who owns this agent
        listId:
          type:
          - number
          - 'null'
          description: ID of the list this agent sources contacts into
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp
      required:
      - id
      - name
      - targetJobTitles
      - targetIndustries
      - targetCompanySizes
      - targetLocations
      - targetCompanyTypes
      - agentType
      - scriptInstalled
      - paused
      - excludeServiceProviders
      - skipIcpFilter
      - includeOpenToWorkProfiles
      - leadWaterfall
      - userId
      - createdAt
      - updatedAt
    AgentVariableV2Dto:
      type: object
      properties:
        type:
          type: string
          description: Type of signal this variable configures
          enum:
          - SEARCH_KEYWORD
          - SEARCH_KEYWORD_COMMENT
          - SEARCH_KEYWORD_LIKE
          - SEARCH_KEYWORD_POST
          - EVENT_KEYWORD
          - GROUP_KEYWORD
          - COMPETITOR_PAGE_URL
          - INFLUENCER_PAGE_URL
          - YOUR_COMPANY
          - RECENT_ACTIVITY
          - RECENTLY_CHANGED_JOB
          - RECENT_FUNDING_EVENT
          - VISITED_PROFILE
          - YOUR_PROFILE
          - YOUR_COMPANY_FOLLOWERS
          - JOB_SEARCH
          - HIRING
          - TECHNOLOGY
          - LOOKALIKE
        value:
          type: string
          description: Value of the variable; its meaning depends on the type (e.g. a search keyword for SEARCH_KEYWORD, a page URL for COMPETITOR_PAGE_URL)
        options:
          type: object
          description: Type-specific configuration object (e.g. JOB_SEARCH stores { job_type, geocode })
        enabled:
          type: boolean
          description: Whether the variable is enabled and will be used in runs
        needsUserToken:
          type: boolean
          description: Whether running this variable requires a connected LinkedIn account token
        linkedinSeatId:
          type: number
          description: ID of the LinkedIn seat used to run this variable
      required:
      - type
      - value
  securitySchemes:
    API-Key:
      scheme: bearer
      bearerFormat: JWT
      type: http
      name: JWT
      description: Enter API Key
      in: header