Gojiberry AI Unibox API

openapi: 3.2.0
info:
  title: Gojiberry AI - External Unibox API
  description: '# Gojiberry AI External API


    This API allows you to programmatically access your Gojiberry AI data and integrate it with your applications. ## How it works


    Gojiberry runs your outreach as a pipeline of three building blocks:


    1. **Source agent — the lead finder.** A source agent continuously sources leads matching your targeting criteria (job titles, industries, locations, signals, ...) and scores them with AI. 2. **List — where the leads land.** Every source agent is linked to a list (`listId` is required when creating an agent): the leads it finds are imported as contacts into that list. Lists can also be filled by importing contacts yourself. 3. **Campaign — the outreach.** A campaign uses one or more lists as its lead source (`listIds` is required when creating a campaign) and runs its steps (LinkedIn invitations, messages, emails, ...) on the contacts of those lists, sending through your LinkedIn and/or email seats. Once activated, the campaign runs the outreach automatically on a daily basis. **Terminology.** In the Gojiberry platform, an **Agent** is a *campaign agent* — the campaign that performs the outreach. A **source agent** is the lead finder that sources the leads. The two are linked through a **list**: the source agent imports the leads it finds into the list, and the campaign agent reaches out to the contacts of that list. **Best practice: create a Full Cycle agent.** Always create the three resources in this order — first the list, then the source agent that fills it, then the campaign that reaches out to it. Together, the list + source agent + campaign agent form a **Full Cycle agent**: leads are sourced and outreached automatically, end to end. If you create a source agent without a campaign agent, it shows up as a **legacy agent** in the platform: it only sources leads and does **no outreach**. So it''s best practice to always create all three. A typical setup through the API:


    ```text

    POST /v1/list # 1. create the list

    POST /v1/agent # 2. create the source agent (lead finder) linked to that list (listId)

    POST /v1/campaign # 3. create the campaign agent using that list as lead source (listIds)

    GET /v1/campaign/{id}/logs # 4. follow the outreach activity

    ```


    ## Authentication


    All API requests require authentication using a Bearer token. To get your API key:


    1. **Log in to your Gojiberry AI account** at https://app.gojiberry.ai

    2. **Navigate to Settings** → **API** section

    3. **Click "Create API Key"** to generate a new token

    4. **Copy the API key** when it''s displayed (you won''t be able to see it again)

    5. **Use the token** in your requests by adding the header: `Authorization: Bearer YOUR_API_KEY`


    ## Impersonation (organization owners)


    If your API key belongs to the **owner of an organization**, you can perform any API call on behalf of another member of your organization by adding the `x-impersonate-user-id` header with the member''s user ID:


    ```bash

    # Get the contacts of the organization member with user ID 123

    curl -H "Authorization: Bearer YOUR_API_KEY" \

    -H "x-impersonate-user-id: 123" \

    https://ext.gojiberry.ai/v1/contact

    ```


    When impersonating, the request behaves exactly as if it was made by that member: you read and write their data (contacts, campaigns, lists, unibox, etc.). Rules:

    - Your API key must belong to the **organization owner**; other members cannot impersonate. - The impersonated user must belong to the **same organization** as the API key user. - Requests that don''t meet these rules are rejected with a `401 Unauthorized`. Tip: use `GET /v1/organization/members` to list the members of your organization and their user IDs, and `GET /v1/user/me` to verify which user the current request acts as. ## Rate Limits


    - **100 requests per minute** per account. Short bursts above this are tolerated. - **100,000 requests per day** per account.'
  version: '1.0'
  contact: {}
servers:
- url: https://ext.gojiberry.ai
  description: Production
tags:
- name: Unibox
paths:
  /v1/unibox/contact/{contactId}:
    get:
      operationId: UniboxExternalController_getMessagesByContactId
      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: contactId
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      tags:
      - Unibox
      summary: Unibox external controller get messages by contact id
      x-summary-source: derived
  /v1/unibox/threads:
    get:
      description: Returns paginated unibox threads for a specific LinkedIn seat when seatId is provided. If no seatId is provided, it returns threads for all LinkedIn seats in the account.
      operationId: UniboxExternalController_getThreads
      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: dateTo
        required: false
        in: query
        description: Filter threads with lastMessageDate on or before this ISO date string.
        schema:
          type: string
      - name: dateFrom
        required: false
        in: query
        description: Filter threads with lastMessageDate on or after this ISO date string.
        schema:
          type: string
      - name: seen
        required: false
        in: query
        description: Filter threads by seen/read status. Use true or false.
        schema:
          type: boolean
      - name: interested
        required: false
        in: query
        description: Filter threads by interested status. Use true or false.
        schema:
          type: boolean
      - name: attendeeFullName
        required: false
        in: query
        description: Filter threads by attendee full name. Partial matches are supported.
        schema:
          type: string
      - name: order
        required: false
        in: query
        description: 'Sort direction by last message date. Default: DESC.'
        schema:
          enum:
          - ASC
          - DESC
          type: string
      - name: limit
        required: false
        in: query
        description: 'Number of threads per page. Default: 20. Minimum: 1. Maximum: 100.'
        schema:
          type: number
      - name: page
        required: false
        in: query
        description: 'Page number. Default: 1. Minimum: 1.'
        schema:
          type: number
      - name: seatId
        required: false
        in: query
        description: Optional LinkedIn seat ID. If omitted, returns threads for all seats in the account.
        schema:
          type: number
      responses:
        '200':
          description: Paginated unibox threads retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unibox2ThreadsPageDto'
      security:
      - bearer: []
      summary: Get unibox threads
      tags:
      - Unibox
  /v1/unibox/threads/{threadId}/messages:
    get:
      description: Returns paginated unibox messages for a thread owned by the authenticated user.
      operationId: UniboxExternalController_getThreadMessages
      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: threadId
        required: true
        in: path
        schema:
          type: number
      - name: order
        required: false
        in: query
        description: 'Sort direction by message creation date. Default: ASC.'
        schema:
          enum:
          - ASC
          - DESC
          type: string
      - name: limit
        required: false
        in: query
        description: 'Number of messages per page. Default: 50. Minimum: 1. Maximum: 200.'
        schema:
          type: number
      - name: page
        required: false
        in: query
        description: 'Page number. Default: 1. Minimum: 1.'
        schema:
          type: number
      responses:
        '200':
          description: Paginated unibox messages retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unibox2MessagesPageDto'
      security:
      - bearer: []
      summary: Get unibox messages from a thread
      tags:
      - Unibox
  /v1/unibox/messages/send-message:
    post:
      description: 'Sends a LinkedIn message in a unibox thread. Provide chatId and message in the body. chatId is the internal unibox thread id returned as id by GET /v1/unibox/threads; it is not the LinkedIn conversationUrn. Optional multipart fields: file, voiceMessage.'
      operationId: UniboxExternalController_sendMessage
      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
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - chatId
              properties:
                chatId:
                  type: string
                  description: Internal unibox thread id returned as id by GET /v1/unibox/threads. This is not the LinkedIn conversationUrn.
                message:
                  type: string
                  description: Text message to send. Optional only when sending a file or voiceMessage.
                  example: Hi, thanks for your reply.
                file:
                  type: string
                  format: binary
                  description: Optional file attachment. Do not send together with voiceMessage.
                voiceMessage:
                  type: string
                  format: binary
                  description: Optional voice message attachment. Do not send together with file.
      responses:
        '201':
          description: Message sent successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unibox2Message'
      security:
      - bearer: []
      summary: Send a unibox LinkedIn message
      tags:
      - Unibox
  /v1/unibox/messages/download-attachment/{messageId}/{attachmentId}:
    get:
      description: 'Downloads an attachment from a unibox message, returned as base64 with its mime type. Please note: each call fetches the attachment live from the connected LinkedIn account. To keep that account healthy, we recommend downloading each attachment once and caching it on your side rather than calling this endpoint repeatedly. This endpoint is rate limited to 10 requests per minute.'
      operationId: UniboxExternalController_downloadAttachment
      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: messageId
        required: true
        in: path
        schema:
          type: string
      - name: attachmentId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Attachment downloaded successfully, returned as base64 with its mime type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unibox2AttachmentDownloadDto'
        '404':
          description: Message or attachment not found.
        '429':
          description: Rate limit exceeded (10 requests per minute).
      security:
      - bearer: []
      summary: Download a unibox message attachment
      tags:
      - Unibox
components:
  schemas:
    Unibox2MessageAttachmentDto:
      type: object
      properties:
        id:
          type: string
          description: Attachment id, used by the download endpoint
        url:
          type: string
          description: LinkedIn URL of the attachment
        type:
          type: string
          description: Kind of attachment
          enum:
          - img
          - video
          - audio
          - file
          - linkedin_post
        name:
          type: string
          description: File name
        size:
          type: number
          description: Size in bytes
      required:
      - id
      - url
      - type
      - name
      - size
    Unibox2Message:
      type: object
      properties:
        id:
          type: number
          description: Incremental message id
        threadId:
          type: number
          description: Parent thread id
        userId:
          type: number
          description: Owner user id
        seatId:
          type:
          - number
          - 'null'
          description: LinkedIn seat id that received/sent the message
        linkedinMessageBackendUrn:
          type:
          - string
          - 'null'
          description: LinkedIn's message backend URN (urn:li:messagingMessage:…). Used with user/thread scoping as the dedup key when the same message arrives via both the realtime SSE stream and the getThread backfill.
        senderUrn:
          type:
          - string
          - 'null'
          description: LinkedIn URN of the sender
        senderFullName:
          type:
          - string
          - 'null'
          description: Full name of the sender
        senderIsSelf:
          type: boolean
          description: True when the sender is the seat owner
        content:
          type:
          - string
          - 'null'
          description: Message content
        attachments:
          description: Attachments attached to the message
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Unibox2MessageAttachmentDto'
        deliveredAt:
          format: date-time
          type:
          - string
          - 'null'
          description: Timestamp LinkedIn assigned when the message was delivered (voyager `deliveredAt`). Distinct from `createdAt`, which is when the row landed in Gojiberry — for backfilled history those can differ by years.
        createdAt:
          format: date-time
          type: string
          description: Timestamp the row was persisted in Gojiberry
      required:
      - id
      - threadId
      - userId
      - senderUrn
      - senderIsSelf
      - createdAt
    Unibox2ThreadsPageDto:
      type: object
      properties:
        data:
          description: Threads on this page, ordered by last message date
          type: array
          items:
            $ref: '#/components/schemas/Unibox2Thread'
        total:
          type: number
          description: Number of threads matching the filters
        page:
          type: number
          description: Page that was requested. Starts at 1.
        limit:
          type: number
          description: Page size that was requested
        totalPages:
          type: number
          description: Number of pages for this filter
      required:
      - data
      - total
      - page
      - limit
      - totalPages
    Unibox2Thread:
      type: object
      properties:
        id:
          type: number
          description: Incremental thread id
        lastMessage:
          type:
          - string
          - 'null'
          description: Content of the last message in the thread
        lastMessageDate:
          format: date-time
          type:
          - string
          - 'null'
          description: Date of the last message in the thread
        lastMessageFullName:
          type:
          - string
          - 'null'
          description: Full name of the sender of the last message
        seen:
          type: boolean
          description: Whether the thread has been seen
        attendeeUrn:
          type:
          - string
          - 'null'
          description: LinkedIn URN of the attendee (conversation partner)
        conversationUrn:
          type:
          - string
          - 'null'
          description: LinkedIn conversation URN
        attendeeFullName:
          type:
          - string
          - 'null'
          description: Full name of the attendee
        attendeeProfilePicture:
          type:
          - string
          - 'null'
          description: Profile picture URL of the attendee
        userId:
          type: number
          description: Owner user id
        seatId:
          type:
          - number
          - 'null'
          description: LinkedIn seat id owning the thread
        interested:
          type:
          - boolean
          - 'null'
          description: 'Sentiment: whether the attendee is interested'
        interestedReasoning:
          type:
          - string
          - 'null'
          description: Reasoning behind the interested classification
        aiGeneratedReply:
          type:
          - string
          - 'null'
          description: AI-generated draft reply for the operator to review
        contactId:
          type:
          - number
          - 'null'
          description: Linked Gojiberry contact id, when matched
        createdAt:
          format: date-time
          type: string
          description: When the thread row was created
        updatedAt:
          format: date-time
          type: string
          description: When the thread row was last updated
      required:
      - id
      - seen
      - attendeeUrn
      - userId
      - createdAt
      - updatedAt
    Unibox2MessagesPageDto:
      type: object
      properties:
        data:
          description: Messages on this page
          type: array
          items:
            $ref: '#/components/schemas/Unibox2Message'
        total:
          type: number
          description: Number of messages in the thread
        page:
          type: number
          description: Page that was requested. Starts at 1.
        limit:
          type: number
          description: Page size that was requested
        totalPages:
          type: number
          description: Number of pages in the thread
      required:
      - data
      - total
      - page
      - limit
      - totalPages
    Unibox2AttachmentDownloadDto:
      type: object
      properties:
        base64:
          type: string
          description: Attachment bytes, base64-encoded
        mimeType:
          type: string
          description: MIME type of the attachment
          example: image/jpeg
      required:
      - base64
      - mimeType
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Enter API Key
x-provenance:
  method: harvested
  publisher: Gojiberry AI
  source: https://ext.gojiberry.ai/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)