openapi: 3.1.0
info:
  title: GraphKit API v1
  version: 0.1.0
  description: "The public GraphKit REST API. Authenticate with `Authorization:
    Bearer gk_live_...`. Docs: https://docs.graphkit.com/api/"
servers:
  - url: https://app.graphkit.com
security:
  - apiKey: []
tags:
  - name: v1
paths:
  /api/v1/me:
    get:
      tags:
        - v1
      operationId: v1GetMe
      description: Returns the key (id, name, prefix and scopes) and its workspace.
        Never returns the secret.
      security:
        - apiKey: []
      responses:
        "200":
          description: The key and the workspace it acts on.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1Me"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
      summary: Get the current key
  /api/v1/accounts:
    get:
      tags:
        - v1
      operationId: v1ListAccounts
      description: Connected accounts on every channel, newest first. `status` is one
        of `connecting`, `active`, `reconnect_required`, `restricted`, `paused`
        or `disconnected`; `statusReason` says why.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Connected accounts.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1AccountPage"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
      summary: List accounts
  /api/v1/accounts/{id}:
    get:
      tags:
        - v1
      operationId: v1GetAccount
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
      responses:
        "200":
          description: Account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1Account"
        "404":
          $ref: "#/components/responses/Error"
      summary: Get an account
      description: One connected account by id.
  /api/v1/leads:
    get:
      tags:
        - v1
      operationId: v1ListLeads
      description: Leads newest first. Filter by list with `listId`, or search with
        `q`, which matches the name, company or email.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
        - name: listId
          in: query
          required: false
          schema:
            type: string
            format: uuid
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Matches name, company or email.
      responses:
        "200":
          description: Leads.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1LeadPage"
      summary: List leads
    post:
      tags:
        - v1
      operationId: v1UpsertLead
      description: >-
        Creates a lead, or merges into the lead that already owns one of the
        identities. An identity `value` can be a profile URL, a public id, an
        `@username` or a `+E.164` phone number, depending on the channel. A
        `profileUrl` with no `identities` is read as a LinkedIn identity.


        Merging only fills empty fields, and never changes a field a teammate
        edited by hand. The response is `201` when the lead was created and
        `200` when it was merged, with `outcome` set to `created`, `updated` or
        `duplicate`. `conflicts` lists identities that already belong to a
        different lead; they stay with that lead, and leads are never merged
        automatically.


        A lead created here emits the `lead.created` webhook.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1UpsertLeadRequest"
      responses:
        "200":
          description: Merged.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1UpsertLeadResult"
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1UpsertLeadResult"
        "400":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
      summary: Create or merge a lead
  /api/v1/leads/{id}:
    get:
      tags:
        - v1
      operationId: v1GetLead
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
      responses:
        "200":
          description: Lead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1Lead"
        "404":
          $ref: "#/components/responses/Error"
      summary: Get a lead
      description: One lead with its identities and list ids.
  /api/v1/lists:
    get:
      tags:
        - v1
      operationId: v1ListLists
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Lead lists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1ListPage"
      summary: List lists
      description: Lead lists newest first, with their lead counts.
    post:
      tags:
        - v1
      operationId: v1CreateList
      description: Creates an empty list.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1CreateListRequest"
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1List"
        "400":
          $ref: "#/components/responses/Error"
      summary: Create a list
  /api/v1/lists/{id}/leads:
    post:
      tags:
        - v1
      operationId: v1AddLeadsToList
      description: Adds 1 to 1000 leads. Leads already in the list are counted in
        `alreadyPresent`, and ids that are not leads of this workspace are
        returned in `unknownLeadIds`.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1LeadIdsRequest"
      responses:
        "200":
          description: Outcome.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1BatchResult"
        "404":
          $ref: "#/components/responses/Error"
      summary: Add leads to a list
  /api/v1/campaigns:
    get:
      tags:
        - v1
      operationId: v1ListCampaigns
      description: Campaigns newest first, each with enrollment counts. Filter with
        `status`.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - draft
              - scheduled
              - active
              - paused
              - completed
              - archived
      responses:
        "200":
          description: Campaigns.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1CampaignPage"
      summary: List campaigns
  /api/v1/campaigns/{id}:
    get:
      tags:
        - v1
      operationId: v1GetCampaign
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
      responses:
        "200":
          description: Campaign.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1Campaign"
        "404":
          $ref: "#/components/responses/Error"
      summary: Get a campaign
      description: One campaign with its enrollment counts.
  /api/v1/campaigns/{id}/stats:
    get:
      tags:
        - v1
      operationId: v1CampaignStats
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
        - $ref: "#/components/parameters/AnalyticsFrom"
        - $ref: "#/components/parameters/AnalyticsTo"
        - $ref: "#/components/parameters/AnalyticsDays"
      responses:
        "200":
          description: Campaign metrics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1CampaignStats"
        "404":
          $ref: "#/components/responses/Error"
      summary: Get campaign stats
      description: >-
        The same metrics as the app's analytics page for this campaign: totals
        for the range, totals for the previous range of the same length, and one
        row per day. Days are local to the workspace time zone.


        Pass `from` and `to` (`YYYY-MM-DD`, inclusive), or `days` for the last N
        days. The default is the last 30 days. Metric definitions are in
        [Analytics](/guides/analytics/#metric-definitions). Rates are `null`
        when their denominator is 0.
  /api/v1/campaigns/{id}/leads:
    post:
      tags:
        - v1
      operationId: v1EnrollLeads
      description: >-
        Adds leads as pending enrollments at the entry step, with `leadIds` (1
        to 1000) or every lead of `listId`. The scheduler starts them inside the
        campaign's sending windows.


        Leads already in the campaign, suppressed leads and leads active in
        another campaign of the workspace are skipped and counted. Completed and
        archived campaigns return `409 invalid_state`.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1LeadIdsRequest"
      responses:
        "200":
          description: Outcome.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1EnrollResult"
        "404":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
      summary: Add leads to a campaign
  /api/v1/campaigns/{id}/pause:
    post:
      tags:
        - v1
      operationId: v1PauseCampaign
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Paused.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1Campaign"
        "409":
          $ref: "#/components/responses/Error"
      summary: Pause a campaign
      description: Pauses an active or scheduled campaign. Leads keep their place and
        continue from it on resume.
  /api/v1/campaigns/{id}/resume:
    post:
      tags:
        - v1
      operationId: v1ResumeCampaign
      description: Resumes a paused campaign and emits `campaign.started`. Draft
        campaigns are launched in the app, where the sequence is validated.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Active again.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1Campaign"
        "402":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
      summary: Resume a campaign
  /api/v1/conversations:
    get:
      tags:
        - v1
      operationId: v1ListConversations
      description: Conversations sorted by latest activity. Filter by `channel`,
        `accountId`, `leadId` or `unread=true`. Private conversations are never
        returned.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/AnalyticsChannel"
        - name: accountId
          in: query
          required: false
          schema:
            type: string
            format: uuid
        - name: leadId
          in: query
          required: false
          schema:
            type: string
            format: uuid
        - name: unread
          in: query
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Conversations.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1ConversationPage"
      summary: List conversations
  /api/v1/conversations/{id}/messages:
    get:
      tags:
        - v1
      operationId: v1ListMessages
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Messages, newest first.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1MessagePage"
        "404":
          $ref: "#/components/responses/Error"
      summary: List messages
      description: Messages of one conversation, newest first.
    post:
      tags:
        - v1
      operationId: v1SendMessage
      description: >-
        Queues a reply from the conversation's own account, with the same rules
        as the inbox composer: channel message limits, opt-outs and account
        status all apply. The response is `202` with the pending message; it is
        sent in the background.


        The reply is attributed to the user who created the API key. Subscribe
        to `message.sent` to learn when it was delivered.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - body
              additionalProperties: false
              properties:
                body:
                  type: string
      responses:
        "202":
          description: Queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1Message"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
      summary: Send a reply
  /api/v1/webhooks:
    get:
      tags:
        - v1
      operationId: v1ListWebhooks
      description: Endpoints of the workspace with their status and failure streak.
      security:
        - apiKey: []
      responses:
        "200":
          description: Endpoints.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1WebhookPage"
      summary: List webhook endpoints
    post:
      tags:
        - v1
      operationId: v1CreateWebhook
      description: Creates an endpoint. An empty `events` list subscribes to every
        event. The `whsec_` signing secret is returned once, in this response
        only. In production the URL must use https and resolve to a public
        address.
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWebhookEndpointRequest"
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedWebhookEndpoint"
        "400":
          $ref: "#/components/responses/Error"
      summary: Create a webhook endpoint
  /api/v1/webhooks/{id}:
    delete:
      tags:
        - v1
      operationId: v1DeleteWebhook
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/V1Id"
      responses:
        "204":
          description: Deleted.
        "404":
          $ref: "#/components/responses/Error"
      summary: Delete a webhook endpoint
      description: Deletes the endpoint. It receives no further deliveries.
  /api/v1/webhook-events:
    get:
      tags:
        - v1
      operationId: v1WebhookEvents
      security:
        - apiKey: []
      responses:
        "200":
          description: Event catalogue.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - nextCursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/WebhookEventInfo"
                  nextCursor:
                    type:
                      - string
                      - "null"
      summary: List event types
      description: The event catalogue, with a description and an example `data`
        object for each type.
components:
  schemas:
    V1Me:
      type: object
      required:
        - apiKey
        - workspace
      properties:
        apiKey:
          type: object
          required:
            - id
            - name
            - prefix
            - scopes
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            prefix:
              type: string
            scopes:
              type: array
              items:
                $ref: "#/components/schemas/ApiScope"
        workspace:
          type: object
          required:
            - id
            - name
            - organizationId
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            organizationId:
              type: string
              format: uuid
    ApiScope:
      type: string
      description: "mcp:* open the MCP server (/mcp): mcp:read and mcp:write cover
        every area, mcp:<area>:read|write one area (write implies read).
        kit:read and kit:write are older names of mcp:read and mcp:write."
      enum:
        - workspace:read
        - senders:read
        - leads:read
        - leads:write
        - campaigns:read
        - campaigns:write
        - inbox:read
        - inbox:write
        - webhooks:manage
        - kit:read
        - kit:write
        - mcp:read
        - mcp:write
        - mcp:accounts:read
        - mcp:accounts:write
        - mcp:leads:read
        - mcp:leads:write
        - mcp:campaigns:read
        - mcp:campaigns:write
        - mcp:inbox:read
        - mcp:inbox:write
        - mcp:analytics:read
        - mcp:analytics:write
        - mcp:integrations:read
        - mcp:integrations:write
        - mcp:workspace:read
        - mcp:workspace:write
        - mcp:billing:read
        - mcp:billing:write
        - mcp:autopilot:read
        - mcp:autopilot:write
        - mcp:infrastructure:read
        - mcp:infrastructure:write
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: snake_case machine code
            message:
              type: string
            details:
              type: object
              additionalProperties: true
              description: Optional counts the UI shows (billing errors such as seats_in_use).
    V1AccountPage:
      type: object
      required:
        - data
        - nextCursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/V1Account"
        nextCursor:
          $ref: "#/components/schemas/NullableString"
    V1Account:
      type: object
      required:
        - id
        - channel
        - displayName
        - handle
        - profileUrl
        - avatarUrl
        - status
        - statusReason
        - connectedAt
        - lastSyncedAt
        - isDemo
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        channel:
          $ref: "#/components/schemas/Channel"
        displayName:
          type: string
        handle:
          $ref: "#/components/schemas/NullableString"
        profileUrl:
          $ref: "#/components/schemas/NullableString"
        avatarUrl:
          $ref: "#/components/schemas/NullableString"
        status:
          type: string
        statusReason:
          $ref: "#/components/schemas/NullableString"
        connectedAt:
          $ref: "#/components/schemas/NullableDateTime"
        lastSyncedAt:
          $ref: "#/components/schemas/NullableDateTime"
        isDemo:
          type: boolean
        createdAt:
          type: string
          format: date-time
    Channel:
      type: string
      description: One of `linkedin`, `instagram`, `whatsapp`, `telegram`, `facebook`.
      enum:
        - linkedin
        - instagram
        - whatsapp
        - telegram
        - facebook
    NullableString:
      type:
        - string
        - "null"
    NullableDateTime:
      type:
        - string
        - "null"
      format: date-time
    V1LeadPage:
      type: object
      required:
        - data
        - nextCursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/V1Lead"
        nextCursor:
          $ref: "#/components/schemas/NullableString"
    V1Lead:
      type: object
      required:
        - id
        - firstName
        - lastName
        - fullName
        - headline
        - jobTitle
        - companyName
        - location
        - email
        - phone
        - profileUrl
        - avatarUrl
        - customFields
        - source
        - isDemo
        - identities
        - listIds
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        firstName:
          $ref: "#/components/schemas/NullableString"
        lastName:
          $ref: "#/components/schemas/NullableString"
        fullName:
          $ref: "#/components/schemas/NullableString"
        headline:
          $ref: "#/components/schemas/NullableString"
        jobTitle:
          $ref: "#/components/schemas/NullableString"
        companyName:
          $ref: "#/components/schemas/NullableString"
        location:
          $ref: "#/components/schemas/NullableString"
        email:
          $ref: "#/components/schemas/NullableString"
        phone:
          $ref: "#/components/schemas/NullableString"
        profileUrl:
          $ref: "#/components/schemas/NullableString"
        avatarUrl:
          $ref: "#/components/schemas/NullableString"
        customFields:
          type: object
          additionalProperties: true
        source:
          type: string
        isDemo:
          type: boolean
        identities:
          type: array
          items:
            type: object
            required:
              - channel
              - handle
              - profileUrl
              - isPrimary
              - verified
            properties:
              channel:
                $ref: "#/components/schemas/Channel"
              handle:
                $ref: "#/components/schemas/NullableString"
              profileUrl:
                $ref: "#/components/schemas/NullableString"
              isPrimary:
                type: boolean
              verified:
                type: boolean
        listIds:
          type: array
          items:
            type: string
            format: uuid
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    V1UpsertLeadRequest:
      type: object
      additionalProperties: false
      description: At least one identity (or profileUrl, read as a LinkedIn identity).
      properties:
        firstName:
          type: string
        lastName:
          type: string
        fullName:
          type: string
        headline:
          type: string
        jobTitle:
          type: string
        companyName:
          type: string
        location:
          type: string
        email:
          type: string
        phone:
          type: string
        profileUrl:
          type: string
        identities:
          type: array
          maxItems: 8
          items:
            type: object
            required:
              - channel
              - value
            properties:
              channel:
                $ref: "#/components/schemas/Channel"
              value:
                type: string
                description: Profile URL, public id, @username or +E.164 phone.
        customFields:
          type: object
          additionalProperties:
            type: string
        listIds:
          type: array
          maxItems: 20
          items:
            type: string
            format: uuid
    V1UpsertLeadResult:
      type: object
      required:
        - outcome
        - lead
        - conflicts
      properties:
        outcome:
          type: string
          enum:
            - created
            - updated
            - duplicate
        lead:
          $ref: "#/components/schemas/V1Lead"
        conflicts:
          type: array
          items:
            type: string
          description: Identities already owned by another lead (left there).
    V1ListPage:
      type: object
      required:
        - data
        - nextCursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/V1List"
        nextCursor:
          $ref: "#/components/schemas/NullableString"
    V1List:
      type: object
      required:
        - id
        - name
        - description
        - source
        - leadCount
        - isDemo
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          $ref: "#/components/schemas/NullableString"
        source:
          type: string
        leadCount:
          type: integer
        isDemo:
          type: boolean
        createdAt:
          type: string
          format: date-time
    V1CreateListRequest:
      type: object
      required:
        - name
      additionalProperties: false
      properties:
        name:
          type: string
          maxLength: 120
        description:
          type: string
          maxLength: 500
    V1LeadIdsRequest:
      type: object
      additionalProperties: false
      description: leadIds (1–1000); campaigns also accept listId instead.
      properties:
        leadIds:
          type: array
          maxItems: 1000
          items:
            type: string
            format: uuid
        listId:
          type: string
          format: uuid
    V1BatchResult:
      type: object
      required:
        - added
        - alreadyPresent
        - unknownLeadIds
      properties:
        added:
          type: integer
        alreadyPresent:
          type: integer
        unknownLeadIds:
          type: array
          items:
            type: string
            format: uuid
    V1CampaignPage:
      type: object
      required:
        - data
        - nextCursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/V1Campaign"
        nextCursor:
          $ref: "#/components/schemas/NullableString"
    V1Campaign:
      type: object
      required:
        - id
        - name
        - description
        - status
        - channels
        - dryRun
        - stopOnReply
        - isDemo
        - launchedAt
        - pausedAt
        - completedAt
        - createdAt
        - enrollments
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          $ref: "#/components/schemas/NullableString"
        status:
          type: string
          enum:
            - draft
            - scheduled
            - active
            - paused
            - completed
            - archived
        channels:
          type: array
          items:
            type: string
        dryRun:
          type: boolean
        stopOnReply:
          type: boolean
        isDemo:
          type: boolean
        launchedAt:
          $ref: "#/components/schemas/NullableDateTime"
        pausedAt:
          $ref: "#/components/schemas/NullableDateTime"
        completedAt:
          $ref: "#/components/schemas/NullableDateTime"
        createdAt:
          type: string
          format: date-time
        enrollments:
          type: object
          required:
            - total
            - active
            - completed
            - stopped
          properties:
            total:
              type: integer
            active:
              type: integer
            completed:
              type: integer
            stopped:
              type: integer
    V1CampaignStats:
      type: object
      required:
        - campaignId
        - range
        - totals
        - previousTotals
        - days
      properties:
        campaignId:
          type: string
          format: uuid
        range:
          $ref: "#/components/schemas/AnalyticsRange"
        totals:
          $ref: "#/components/schemas/AnalyticsMetrics"
        previousTotals:
          $ref: "#/components/schemas/AnalyticsMetrics"
        days:
          type: array
          items:
            $ref: "#/components/schemas/AnalyticsDay"
    AnalyticsRange:
      type: object
      required:
        - from
        - to
        - days
        - timezone
      properties:
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        days:
          type: integer
        timezone:
          type: string
    AnalyticsMetrics:
      type: object
      required:
        - invitesSent
        - invitesAccepted
        - acceptanceRate
        - messagesSent
        - campaignMessages
        - manualMessages
        - inmailsSent
        - profileVisits
        - follows
        - likes
        - contacted
        - replies
        - replyRate
        - positiveReplies
        - positiveRate
        - messagesReceived
        - newConnections
        - failedActions
        - emailHandoffs
        - emailReplies
      description: "Counts of stored events. Definitions:
        https://docs.graphkit.com/guides/analytics/#metric-definitions"
      properties:
        invitesSent:
          type: integer
        invitesAccepted:
          type: integer
          description: Invites sent in the range whose lead later connected with the same
            account.
        acceptanceRate:
          $ref: "#/components/schemas/NullableRate"
        messagesSent:
          type: integer
        campaignMessages:
          type: integer
        manualMessages:
          type: integer
        inmailsSent:
          type: integer
        profileVisits:
          type: integer
        follows:
          type: integer
        likes:
          type: integer
        contacted:
          type: integer
          description: Conversations with an outbound message in the range.
        replies:
          type: integer
          description: Conversations whose first inbound message in the range follows an
            outbound one.
        replyRate:
          $ref: "#/components/schemas/NullableRate"
        positiveReplies:
          type: integer
        positiveRate:
          $ref: "#/components/schemas/NullableRate"
        messagesReceived:
          type: integer
        newConnections:
          type: integer
        failedActions:
          type: integer
        emailHandoffs:
          type: integer
          description: Leads handed to a connected email platform (succeeded email_handoff
            steps).
        emailReplies:
          type: integer
          description: First email reply per lead, connection and platform campaign, as
            reported by the email platform (source = platform). Not included in
            replies.
    NullableRate:
      type:
        - number
        - "null"
      description: Ratio 0..1; null when the denominator is 0.
    AnalyticsDay:
      allOf:
        - $ref: "#/components/schemas/AnalyticsMetrics"
        - type: object
          required:
            - date
          properties:
            date:
              type: string
              format: date
    V1EnrollResult:
      type: object
      required:
        - added
        - alreadyPresent
        - suppressed
        - activeElsewhere
        - unknownLeadIds
      properties:
        added:
          type: integer
          description: New pending enrollments.
        alreadyPresent:
          type: integer
          description: Leads already enrolled in this campaign.
        suppressed:
          type: integer
          description: Leads skipped because one of their identities is suppressed
            (opt-out, blocklist).
        activeElsewhere:
          type: integer
          description: Leads skipped because they are active in another campaign of the
            workspace.
        unknownLeadIds:
          type: array
          items:
            type: string
            format: uuid
    V1ConversationPage:
      type: object
      required:
        - data
        - nextCursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/V1Conversation"
        nextCursor:
          $ref: "#/components/schemas/NullableString"
    V1Conversation:
      type: object
      required:
        - id
        - channel
        - accountId
        - leadId
        - campaignId
        - isUnread
        - unreadCount
        - lastMessageAt
        - lastMessagePreview
        - lastMessageDirection
        - archived
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        channel:
          $ref: "#/components/schemas/Channel"
        accountId:
          type: string
          format: uuid
        leadId:
          type:
            - string
            - "null"
          format: uuid
        campaignId:
          type:
            - string
            - "null"
          format: uuid
        isUnread:
          type: boolean
        unreadCount:
          type: integer
        lastMessageAt:
          $ref: "#/components/schemas/NullableDateTime"
        lastMessagePreview:
          $ref: "#/components/schemas/NullableString"
        lastMessageDirection:
          type:
            - string
            - "null"
          enum:
            - inbound
            - outbound
            - null
        archived:
          type: boolean
        createdAt:
          type: string
          format: date-time
    V1MessagePage:
      type: object
      required:
        - data
        - nextCursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/V1Message"
        nextCursor:
          $ref: "#/components/schemas/NullableString"
    V1Message:
      type: object
      required:
        - id
        - direction
        - body
        - status
        - attachments
        - sentByUserId
        - fromCampaign
        - error
        - sentAt
      properties:
        id:
          type: string
          format: uuid
        direction:
          type: string
          enum:
            - inbound
            - outbound
        body:
          type: string
        status:
          type: string
        attachments:
          type: array
          items:
            type: object
            additionalProperties: true
        sentByUserId:
          type:
            - string
            - "null"
          format: uuid
        fromCampaign:
          type: boolean
        error:
          $ref: "#/components/schemas/NullableString"
        sentAt:
          type: string
          format: date-time
    V1WebhookPage:
      type: object
      required:
        - data
        - nextCursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEndpoint"
        nextCursor:
          $ref: "#/components/schemas/NullableString"
    WebhookEndpoint:
      type: object
      required:
        - id
        - workspaceId
        - url
        - description
        - events
        - status
        - disabledReason
        - disabledAt
        - failureCount
        - failingSince
        - lastSuccessAt
        - lastFailureAt
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        workspaceId:
          type: string
          format: uuid
        url:
          type: string
        description:
          $ref: "#/components/schemas/NullableString"
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
          description: Empty means every event.
        status:
          type: string
          enum:
            - active
            - disabled
        disabledReason:
          $ref: "#/components/schemas/NullableString"
        disabledAt:
          $ref: "#/components/schemas/NullableDateTime"
        failureCount:
          type: integer
          description: Consecutive failed attempts.
        failingSince:
          $ref: "#/components/schemas/NullableDateTime"
        lastSuccessAt:
          $ref: "#/components/schemas/NullableDateTime"
        lastFailureAt:
          $ref: "#/components/schemas/NullableDateTime"
        createdAt:
          type: string
          format: date-time
        stats:
          $ref: "#/components/schemas/WebhookEndpointStats"
    WebhookEventType:
      type: string
      enum:
        - account.connected
        - account.disconnected
        - account.reconnect_required
        - lead.created
        - lead.replied
        - invitation.accepted
        - message.received
        - message.sent
        - campaign.started
        - campaign.completed
        - enrollment.completed
        - enrollment.stopped
        - email.replied
        - email.bounced
        - email.unsubscribed
    WebhookEndpointStats:
      type: object
      required:
        - succeeded
        - retrying
        - dead
      properties:
        succeeded:
          type: integer
        retrying:
          type: integer
        dead:
          type: integer
    CreateWebhookEndpointRequest:
      type: object
      required:
        - url
      additionalProperties: false
      properties:
        url:
          type: string
          description: https required in production.
        description:
          type: string
          maxLength: 200
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
    CreatedWebhookEndpoint:
      allOf:
        - $ref: "#/components/schemas/WebhookEndpoint"
        - type: object
          required:
            - secret
          properties:
            secret:
              type: string
              description: whsec_… signing secret, shown once.
    WebhookEventInfo:
      type: object
      required:
        - type
        - group
        - description
        - example
      properties:
        type:
          $ref: "#/components/schemas/WebhookEventType"
        group:
          type: string
        description:
          type: string
        example:
          type: object
          additionalProperties: true
  responses:
    Error:
      description: Error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  parameters:
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    V1Id:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: "Replays the stored response for 24 hours (header
        Idempotent-Replayed: true). Reusing a key with a different request is
        422; while the first request runs, 409."
    AnalyticsFrom:
      name: from
      in: query
      required: false
      schema:
        type: string
        format: date
      description: First day (inclusive, local to the workspace). Send with to.
    AnalyticsTo:
      name: to
      in: query
      required: false
      schema:
        type: string
        format: date
      description: Last day (inclusive).
    AnalyticsDays:
      name: days
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 366
      description: Last N days ending today, when from/to are absent.
    AnalyticsChannel:
      name: channel
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/Channel"
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: gk_live_...
