{
  "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.\n\nMerging 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.\n\nA 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.\n\nPass `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.\n\nLeads 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.\n\nThe 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_..."
      }
    }
  }
}
