{
  "openapi": "3.1.0",
  "info": {
    "title": "PumpGTM API",
    "version": "1.1.0",
    "description": "Run outreach from your own backend or agent: plain REST for sequences, leads, people search, replies and webhooks; adding people to any Play in one call; X follower checks; and the Partner API for agencies and platforms that run PumpGTM for many end users from one account (hosted LinkedIn connect links, per-user workspaces, X-PumpGTM-User). The workspace MCP key also authenticates REST. Start at https://pumpgtm.com/docs/api. No browser session required. Versioning: the major version is in the path (/api/v1); v1 only gains fields. A breaking change ships under a new major path while v1 keeps working, and anything scheduled for removal answers with Deprecation: true and a Sunset header at least 90 days ahead (policy: https://pumpgtm.com/docs/api#versioning).",
    "contact": {
      "url": "https://pumpgtm.com"
    }
  },
  "servers": [
    {
      "url": "https://app.pumpgtm.com/api/v1",
      "description": "Production"
    },
    {
      "url": "https://app.pumpgtm.com/api/partner/v1",
      "description": "Partner API (partner workspace key)"
    }
  ],
  "security": [
    {
      "WorkspaceKey": []
    }
  ],
  "tags": [
    {
      "name": "Plays",
      "description": "A Play finds or receives people and messages them with its sequence. Add your own people to any Play with POST /plays/{id}/leads."
    },
    {
      "name": "Sequences",
      "description": "The messages a Play or lead list sends, across LinkedIn, email and X."
    },
    {
      "name": "Leads",
      "description": "Add people straight to a sequence, read and stop leads, and look up X identities."
    },
    {
      "name": "Replies",
      "description": "Read replies waiting on you and answer them."
    },
    {
      "name": "Results",
      "description": "Pace, funnel and the activity ledger."
    },
    {
      "name": "Webhooks",
      "description": "Signed events for replies, leads and connections."
    },
    {
      "name": "People search",
      "description": "Find and enrich people, and read buying signals."
    },
    {
      "name": "Account",
      "description": "Workspaces, connected accounts, sending limits and Energy."
    },
    {
      "name": "Manual review",
      "description": "Advanced. Approve people one by one before a Play messages them. Most integrations never need this; use POST /plays/{id}/leads instead."
    },
    {
      "name": "Partner",
      "description": "Run PumpGTM for many clients with one key."
    }
  ],
  "paths": {
    "/analytics": {
      "get": {
        "operationId": "getAnalytics",
        "tags": [
          "Results"
        ],
        "summary": "Read outreach analytics by Play, Sequence and channel",
        "description": "Read the same outreach results as /analytics: totals, daily activity, Plays and their Sequences, message-step performance, channels and highest/lowest eligible results. Defaults to range=30d and scope=workspace. Team scope requires a personal OAuth or personal delegation key belonging to a current Team owner/admin, used from its own home workspace; shared workspace and operator keys cannot read team scope. Enrolled is all-time current Sequence assignment; other activity uses the selected Pacific-time window. Reply rates use a full 14-day observation window and rankings require 30 eligible people per result. Null rankings mean insufficient or tied results. Clicks are unavailable; meetings have partial coverage. Cached report timestamps are returned explicitly. No message text, lead records, paid lookups or outreach actions. Workspace scope supports the existing X-PumpGTM-Client managed-workspace selection and partner X-PumpGTM-User routing. Team scope cannot be combined with delegation to another workspace. Unknown or repeated query parameters are refused. All returned channels retain their recorded counts, including channels hidden from the dashboard's Channels tab. No message templates or workflow links are returned.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "range",
            "in": "query",
            "schema": {
              "enum": [
                "7d",
                "30d",
                "90d"
              ],
              "default": "30d"
            }
          },
          {
            "name": "scope",
            "in": "query",
            "schema": {
              "enum": [
                "workspace",
                "team"
              ],
              "default": "workspace"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "range": {
                      "enum": [
                        "7d",
                        "30d",
                        "90d"
                      ]
                    },
                    "scope": {
                      "enum": [
                        "workspace",
                        "team"
                      ]
                    },
                    "timezone": {
                      "const": "America/Los_Angeles"
                    },
                    "period": {
                      "type": "object",
                      "properties": {
                        "since": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Inclusive start."
                        },
                        "until": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Exclusive end and report refresh cutoff."
                        },
                        "label": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "since",
                        "until",
                        "label"
                      ]
                    },
                    "totals": {
                      "type": "object",
                      "properties": {
                        "enrolled": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "All-time current Sequence assignment, not enrollments during this range."
                        },
                        "touched": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "invites": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "connections": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "messages": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "replies": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "meetings": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "mature": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "People eligible for the full 14-day reply comparison."
                        },
                        "cohortReplies": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "replyRate": {
                          "anyOf": [
                            {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "Fraction, not a percentage. Null when no people have a complete 14-day window."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "enrolled",
                        "touched",
                        "invites",
                        "connections",
                        "messages",
                        "replies",
                        "meetings",
                        "mature",
                        "cohortReplies",
                        "replyRate"
                      ]
                    },
                    "daily": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string",
                            "format": "date"
                          },
                          "messages": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "replies": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "invites": {
                            "type": "integer",
                            "minimum": 0
                          }
                        },
                        "required": [
                          "date",
                          "messages",
                          "replies",
                          "invites"
                        ]
                      }
                    },
                    "plays": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "enrolled": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "All-time current Sequence assignment, not enrollments during this range."
                          },
                          "touched": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "invites": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "connections": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "messages": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "replies": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "meetings": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "mature": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "People eligible for the full 14-day reply comparison."
                          },
                          "cohortReplies": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "replyRate": {
                            "anyOf": [
                              {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "Fraction, not a percentage. Null when no people have a complete 14-day window."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "sequences": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                },
                                "enrolled": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "All-time current Sequence assignment, not enrollments during this range."
                                },
                                "touched": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "invites": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "connections": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "messages": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "replies": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "meetings": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "mature": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "People eligible for the full 14-day reply comparison."
                                },
                                "cohortReplies": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "replyRate": {
                                  "anyOf": [
                                    {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction, not a percentage. Null when no people have a complete 14-day window."
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "id",
                                "name",
                                "enrolled",
                                "touched",
                                "invites",
                                "connections",
                                "messages",
                                "replies",
                                "meetings",
                                "mature",
                                "cohortReplies",
                                "replyRate"
                              ]
                            }
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "enrolled",
                          "touched",
                          "invites",
                          "connections",
                          "messages",
                          "replies",
                          "meetings",
                          "mature",
                          "cohortReplies",
                          "replyRate",
                          "sequences"
                        ]
                      }
                    },
                    "messages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "enrolled": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "All-time current Sequence assignment, not enrollments during this range."
                          },
                          "touched": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "invites": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "connections": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "messages": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "replies": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "meetings": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "mature": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "People eligible for the full 14-day reply comparison."
                          },
                          "cohortReplies": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "replyRate": {
                            "anyOf": [
                              {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "Fraction, not a percentage. Null when no people have a complete 14-day window."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "sequenceName": {
                            "type": "string"
                          },
                          "channel": {
                            "enum": [
                              "linkedin",
                              "email",
                              "x",
                              "instagram",
                              "whatsapp"
                            ]
                          },
                          "variant": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "rankable": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "enrolled",
                          "touched",
                          "invites",
                          "connections",
                          "messages",
                          "replies",
                          "meetings",
                          "mature",
                          "cohortReplies",
                          "replyRate",
                          "sequenceName",
                          "channel",
                          "variant",
                          "rankable"
                        ]
                      }
                    },
                    "channels": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "enum": [
                              "linkedin",
                              "email",
                              "x",
                              "instagram",
                              "whatsapp"
                            ]
                          },
                          "name": {
                            "type": "string"
                          },
                          "messages": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "touched": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "invites": {
                            "type": "integer",
                            "minimum": 0
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "messages",
                          "touched",
                          "invites"
                        ]
                      }
                    },
                    "team": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "workspaces": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "enrolled": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "All-time current Sequence assignment, not enrollments during this range."
                                  },
                                  "touched": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "invites": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "connections": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "messages": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "replies": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "meetings": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "mature": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "People eligible for the full 14-day reply comparison."
                                  },
                                  "cohortReplies": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "replyRate": {
                                    "anyOf": [
                                      {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction, not a percentage. Null when no people have a complete 14-day window."
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  }
                                },
                                "required": [
                                  "id",
                                  "name",
                                  "enrolled",
                                  "touched",
                                  "invites",
                                  "connections",
                                  "messages",
                                  "replies",
                                  "meetings",
                                  "mature",
                                  "cohortReplies",
                                  "replyRate"
                                ]
                              }
                            }
                          },
                          "required": [
                            "name",
                            "workspaces"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "rankings": {
                      "type": "object",
                      "properties": {
                        "plays": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "highest": {
                                  "type": "object",
                                  "properties": {
                                    "id": {
                                      "type": "string"
                                    },
                                    "name": {
                                      "type": "string"
                                    },
                                    "replyRate": {
                                      "anyOf": [
                                        {
                                          "type": "number",
                                          "minimum": 0,
                                          "maximum": 1,
                                          "description": "Fraction, not a percentage. Null when no people have a complete 14-day window."
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ]
                                    },
                                    "mature": {
                                      "type": "integer",
                                      "minimum": 0
                                    },
                                    "cohortReplies": {
                                      "type": "integer",
                                      "minimum": 0
                                    }
                                  },
                                  "required": [
                                    "id",
                                    "name",
                                    "replyRate",
                                    "mature",
                                    "cohortReplies"
                                  ]
                                },
                                "lowest": {
                                  "type": "object",
                                  "properties": {
                                    "id": {
                                      "type": "string"
                                    },
                                    "name": {
                                      "type": "string"
                                    },
                                    "replyRate": {
                                      "anyOf": [
                                        {
                                          "type": "number",
                                          "minimum": 0,
                                          "maximum": 1,
                                          "description": "Fraction, not a percentage. Null when no people have a complete 14-day window."
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ]
                                    },
                                    "mature": {
                                      "type": "integer",
                                      "minimum": 0
                                    },
                                    "cohortReplies": {
                                      "type": "integer",
                                      "minimum": 0
                                    }
                                  },
                                  "required": [
                                    "id",
                                    "name",
                                    "replyRate",
                                    "mature",
                                    "cohortReplies"
                                  ]
                                }
                              },
                              "required": [
                                "highest",
                                "lowest"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "messages": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "highest": {
                                  "type": "object",
                                  "properties": {
                                    "id": {
                                      "type": "string"
                                    },
                                    "name": {
                                      "type": "string"
                                    },
                                    "replyRate": {
                                      "anyOf": [
                                        {
                                          "type": "number",
                                          "minimum": 0,
                                          "maximum": 1,
                                          "description": "Fraction, not a percentage. Null when no people have a complete 14-day window."
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ]
                                    },
                                    "mature": {
                                      "type": "integer",
                                      "minimum": 0
                                    },
                                    "cohortReplies": {
                                      "type": "integer",
                                      "minimum": 0
                                    }
                                  },
                                  "required": [
                                    "id",
                                    "name",
                                    "replyRate",
                                    "mature",
                                    "cohortReplies"
                                  ]
                                },
                                "lowest": {
                                  "type": "object",
                                  "properties": {
                                    "id": {
                                      "type": "string"
                                    },
                                    "name": {
                                      "type": "string"
                                    },
                                    "replyRate": {
                                      "anyOf": [
                                        {
                                          "type": "number",
                                          "minimum": 0,
                                          "maximum": 1,
                                          "description": "Fraction, not a percentage. Null when no people have a complete 14-day window."
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ]
                                    },
                                    "mature": {
                                      "type": "integer",
                                      "minimum": 0
                                    },
                                    "cohortReplies": {
                                      "type": "integer",
                                      "minimum": 0
                                    }
                                  },
                                  "required": [
                                    "id",
                                    "name",
                                    "replyRate",
                                    "mature",
                                    "cohortReplies"
                                  ]
                                }
                              },
                              "required": [
                                "highest",
                                "lowest"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "plays",
                        "messages"
                      ]
                    },
                    "methodology": {
                      "type": "object",
                      "properties": {
                        "responseDays": {
                          "const": 14
                        },
                        "minimumRankingSample": {
                          "const": 30
                        },
                        "enrolled": {
                          "const": "all_time_current_assignment"
                        },
                        "replies": {
                          "const": "first_recorded_reply"
                        },
                        "replyAttribution": {
                          "const": "last_message_before_first_reply"
                        }
                      },
                      "required": [
                        "responseDays",
                        "minimumRankingSample",
                        "enrolled",
                        "replies",
                        "replyAttribution"
                      ]
                    },
                    "coverage": {
                      "type": "object",
                      "properties": {
                        "clicks": {
                          "const": "unavailable"
                        },
                        "meetings": {
                          "const": "partial"
                        },
                        "unmatchedSendEvents": {
                          "type": "integer",
                          "minimum": 0
                        }
                      },
                      "required": [
                        "clicks",
                        "meetings",
                        "unmatchedSendEvents"
                      ]
                    }
                  },
                  "required": [
                    "range",
                    "scope",
                    "timezone",
                    "period",
                    "totals",
                    "daily",
                    "plays",
                    "messages",
                    "channels",
                    "team",
                    "rankings",
                    "methodology",
                    "coverage"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "personal_connection_required or team_analytics_forbidden; no team report returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "analytics_report_limit: too much history; no partial totals returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "analytics_unavailable: complete report could not be loaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/hubspot": {
      "post": {
        "operationId": "retiredHubspotSignup",
        "tags": [
          "Plays"
        ],
        "summary": "Retired HubSpot signup endpoint",
        "description": "Use POST /plays/{id}/webhook with a Webhook Play. This old endpoint always returns 410 without processing the request.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "responses": {
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "const": "endpoint_replaced"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/plays/{id}/webhook": {
      "post": {
        "operationId": "receivePlaySignup",
        "tags": [
          "Plays"
        ],
        "summary": "Receive a signup event in a Webhook Play",
        "description": "Receives one supplied contact from a backend or automation tool. Workspace bearer authentication scopes tenancy; the URL identifies the Play and expectedRevision pins its revision. dryRun defaults to true and validates without saving. Live events enter review; eligible auto-add uses the linked approved active sequence. No implicit activation or paid identity lookup. Stable Play/eventId identity deduplicates retries; changed contact fields conflict. No Team delegation. Maximum body size 8192 bytes.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedRevision": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 2147483647
                      },
                      {
                        "type": "string",
                        "pattern": "^[1-9][0-9]{0,9}$"
                      }
                    ]
                  },
                  "eventId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120,
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
                  },
                  "name": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 0,
                        "maxLength": 200
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "email": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 0,
                        "maxLength": 320
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "company": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 0,
                        "maxLength": 200
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "title": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 0,
                        "maxLength": 200
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "linkedinUrl": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 0,
                        "maxLength": 500
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "xUsername": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 0,
                        "maxLength": 500
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "dryRun": {
                    "anyOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "enum": [
                          "true",
                          "false"
                        ]
                      }
                    ],
                    "default": true
                  }
                },
                "required": [
                  "expectedRevision",
                  "eventId"
                ],
                "additionalProperties": false
              },
              "example": {
                "expectedRevision": 2,
                "eventId": "railcode:signup_123",
                "name": "Alex Smith",
                "email": "alex@example.com",
                "dryRun": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "status": {
                          "const": "validated"
                        },
                        "dryRun": {
                          "const": true
                        },
                        "contacted": {
                          "const": false
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status",
                        "dryRun",
                        "contacted",
                        "message"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "dryRun": {
                          "const": false
                        },
                        "contacted": {
                          "const": false
                        },
                        "batchId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "candidateId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "reused": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "status",
                        "dryRun",
                        "contacted",
                        "batchId",
                        "candidateId",
                        "reused"
                      ]
                    }
                  ],
                  "description": "Live status is review or queued; a replay reports the saved candidate status. A saved event does not prove delivery."
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds 8192 bytes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type must be application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/plays/{id}/leads": {
      "post": {
        "operationId": "addPlayLeads",
        "tags": [
          "Plays"
        ],
        "summary": "Add people to a Play",
        "description": "Works on any Play. Send leads: 1 to 500 people, each with at least one of linkedinUrl, email or xUsername. They go straight into the Play's sequence and are tagged with the Play, so they show in GET /plays/{id}/leads. Each person is queued for the channels the sequence has steps for; people already known by LinkedIn, email or X handle are skipped. Your request is the approval: a draft sequence is approved and started; a paused sequence takes the people and stays paused. Nothing is sent in this call; an active sequence sends in its next working window. 409 play_has_no_sequence when the Play has none. Reusing requestId with the same body replays the stored result. The older body with candidateIds behaves exactly like POST /plays/{id}/enroll.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "requestId": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$",
                        "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request."
                      },
                      "accountId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 160,
                        "description": "Optional LinkedIn sender: the public id from the partner LinkedIn accounts list or get_workspace channels.linkedin.data.senders.items. Legacy account-name IDs remain accepted. Must be connected in the selected workspace. Omit for automatic assignment; never reassigns existing leads. Sales Navigator uses an explicit selection for both fetching and sending."
                      },
                      "leads": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "person": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 200
                            },
                            "company": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 200
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "title": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 200
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "linkedinUrl": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 500,
                                  "description": "Public LinkedIn /in/ profile URL."
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "email": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "email",
                                  "maxLength": 320
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "xUsername": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 500,
                                  "description": "X handle (with or without @) or x.com profile URL."
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            }
                          },
                          "required": [
                            "person"
                          ],
                          "additionalProperties": false
                        },
                        "minItems": 1,
                        "maxItems": 500
                      }
                    },
                    "required": [
                      "leads"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "expectedRevision": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan."
                      },
                      "sequenceId": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "sequenceRevision": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan."
                      },
                      "candidateIds": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "minItems": 1,
                        "maxItems": 200,
                        "uniqueItems": true
                      }
                    },
                    "required": [
                      "expectedRevision",
                      "sequenceId",
                      "sequenceRevision",
                      "candidateIds"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              "example": {
                "requestId": "crm-sync-20261012-001",
                "leads": [
                  {
                    "person": "Jane Doe",
                    "xUsername": "janedoe",
                    "email": "jane@acme.com"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "playId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "addResult": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "{ method: \"contacts\", batchId, status: \"completed\", sequenceId, sequenceStatus, reused, addedLeadIds[], summary: { submittedCount, addedCount, duplicatesSkipped, invalidSkipped, alreadyInvitedCount }, contacted: false, energyCharged: 0 }"
                    }
                  },
                  "required": [
                    "playId",
                    "addResult"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listEnrolledPlayLeads",
        "tags": [
          "Plays"
        ],
        "summary": "List the Play's leads",
        "description": "Leads in the selected Play, from its runs or added with POST /plays/{id}/leads, with stable cursor pagination. Use each lead ID to read detailed state or stop its automation.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            }
          },
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Pass nextCursor from the previous response until null."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "playId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "leads": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "linkedinUrl": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "email": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "xUserId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^[1-9][0-9]{0,19}$",
                                "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "username": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "sequenceId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "stage": {
                            "type": "string"
                          },
                          "createdAt": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "linkedinUrl",
                          "email",
                          "xUserId",
                          "username",
                          "sequenceId",
                          "stage",
                          "createdAt"
                        ]
                      }
                    },
                    "nextCursor": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "uuid"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "hasMore": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "playId",
                    "leads",
                    "nextCursor",
                    "hasMore"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/x/watches": {
      "post": {
        "operationId": "createXWatch",
        "tags": [
          "Plays"
        ],
        "summary": "Create an X Play",
        "description": "From now on, people who follow the account (followers), engage with any post (every_post) or engage with one post (post, with postUrl) are collected for review and then DMed with the sequence. Pass exactly one of message (a one-step DM sequence is created; customer credential required) or sequenceId (an existing X sequence). Nothing is sent in this call. 409 x_not_connected when the account is not connected.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "source": {
                    "enum": [
                      "followers",
                      "every_post",
                      "post"
                    ]
                  },
                  "postUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Required when source is post: an x.com/{user}/status/{id} URL."
                  },
                  "message": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "sequenceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  },
                  "as": {
                    "type": "string",
                    "pattern": "^@?[A-Za-z0-9_]{1,15}$",
                    "description": "Connected account to act as; defaults to the workspace's account."
                  }
                },
                "required": [
                  "source"
                ],
                "oneOf": [
                  {
                    "required": [
                      "message"
                    ]
                  },
                  {
                    "required": [
                      "sequenceId"
                    ]
                  }
                ]
              },
              "example": {
                "source": "followers",
                "message": "Thanks for the follow, {{firstName}}! What are you building?"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "source": {
                      "type": "string"
                    },
                    "postId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "sequenceId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string"
                    },
                    "as": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "peopleSeen": {
                      "type": "integer"
                    },
                    "waitingForReview": {
                      "type": "integer"
                    },
                    "createdAt": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "source",
                    "postId",
                    "sequenceId",
                    "status",
                    "as",
                    "peopleSeen",
                    "waitingForReview",
                    "createdAt"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listXWatches",
        "tags": [
          "Plays"
        ],
        "summary": "List X Plays with people waiting and funnels",
        "description": "Every X Play (a follower or post-engager watch plus its DM sequence) with how many people are waiting for review and the sequence funnel. Requires the X channel (403 x_channel_disabled otherwise).",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "watches": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "source": {
                            "enum": [
                              "followers",
                              "every_post",
                              "post"
                            ]
                          },
                          "postId": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "sequenceId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "status": {
                            "type": "string"
                          },
                          "as": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "peopleSeen": {
                            "type": "integer"
                          },
                          "waitingForReview": {
                            "type": "integer"
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "funnel": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        },
                        "required": [
                          "id",
                          "source",
                          "postId",
                          "sequenceId",
                          "status",
                          "as",
                          "peopleSeen",
                          "waitingForReview",
                          "createdAt",
                          "funnel"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "watches"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces": {
      "get": {
        "operationId": "listWorkspaces",
        "tags": [
          "Account"
        ],
        "summary": "List accessible workspaces",
        "description": "Use the MCP key without X-PumpGTM-Client. Returns only its workspace and permitted Team workspaces. Select a returned ID on subsequent requests; a header never grants access.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workspaces": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "role": {
                            "enum": [
                              "owner",
                              "admin",
                              "member"
                            ]
                          }
                        },
                        "required": [
                          "id"
                        ]
                      }
                    }
                  },
                  "required": [
                    "workspaces"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/x/accounts": {
      "get": {
        "operationId": "listXAccounts",
        "tags": [
          "Account"
        ],
        "summary": "List connected X identities",
        "description": "Read saved account identities. No provider health check or OAuth refresh.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accounts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "userId": {
                            "type": "string",
                            "pattern": "^[1-9][0-9]{0,19}$",
                            "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                          },
                          "handle": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "userId",
                          "handle"
                        ]
                      }
                    }
                  },
                  "required": [
                    "accounts"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/x/readiness": {
      "get": {
        "operationId": "getXReadiness",
        "tags": [
          "Account"
        ],
        "summary": "Read account, billing and Energy state",
        "description": "Read-only snapshot. Check each section's state/issues; data may be null. Provider health is unverified. A connection or positive follower result does not guarantee delivery.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workspaceId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "asOf": {
                      "type": "string"
                    },
                    "accounts": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "enum": [
                            "complete",
                            "partial",
                            "unavailable"
                          ]
                        },
                        "observedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "data": {
                          "anyOf": [
                            {
                              "type": "object",
                              "additionalProperties": true
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "issues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "message": {
                                "type": "string"
                              },
                              "retryable": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "retryable"
                            ]
                          }
                        }
                      },
                      "required": [
                        "state",
                        "observedAt",
                        "data",
                        "issues"
                      ]
                    },
                    "billing": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "enum": [
                            "complete",
                            "partial",
                            "unavailable"
                          ]
                        },
                        "observedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "data": {
                          "anyOf": [
                            {
                              "type": "object",
                              "additionalProperties": true
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "issues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "message": {
                                "type": "string"
                              },
                              "retryable": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "retryable"
                            ]
                          }
                        }
                      },
                      "required": [
                        "state",
                        "observedAt",
                        "data",
                        "issues"
                      ]
                    },
                    "energy": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "enum": [
                            "complete",
                            "partial",
                            "unavailable"
                          ]
                        },
                        "observedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "data": {
                          "anyOf": [
                            {
                              "type": "object",
                              "additionalProperties": true
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "issues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "message": {
                                "type": "string"
                              },
                              "retryable": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "retryable"
                            ]
                          }
                        }
                      },
                      "required": [
                        "state",
                        "observedAt",
                        "data",
                        "issues"
                      ]
                    },
                    "providerHealthChecked": {
                      "const": false
                    },
                    "deliveryGuaranteed": {
                      "const": false
                    },
                    "note": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "workspaceId",
                    "asOf",
                    "accounts",
                    "billing",
                    "energy",
                    "providerHealthChecked",
                    "deliveryGuaranteed",
                    "note"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/energy": {
      "get": {
        "operationId": "getEnergy",
        "tags": [
          "Account"
        ],
        "summary": "Read this period's Energy balance",
        "description": "Energy for the current month on a metered workspace: allowance, used, remaining, per-action costs and cents per Energy. { enabled: false } when the workspace is not metered. Partner end users draw from the partner's pool. A balance is not a reservation.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "used": {
                      "type": "integer"
                    },
                    "remaining": {
                      "type": "integer"
                    },
                    "periodStart": {
                      "type": "string"
                    },
                    "costs": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "centsPerEnergy": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "enabled"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/x/users/resolve": {
      "post": {
        "operationId": "resolveXIdentity",
        "tags": [
          "Leads"
        ],
        "summary": "Resolve a handle to a numeric X ID",
        "description": "One exact public handle lookup through the public X data provider. No email-to-X enrichment or fuzzy identity matching. An unverified or unavailable profile returns HTTP 503 with status unknown and user null. No official X fallback.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "type": "string",
                    "pattern": "^@?[A-Za-z0-9_]{1,15}$",
                    "description": "Public X handle, with optional @. Case-insensitive."
                  }
                },
                "required": [
                  "username"
                ],
                "additionalProperties": false
              },
              "example": {
                "username": "example_handle"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "resolved"
                    },
                    "user": {
                      "type": "object",
                      "properties": {
                        "xUserId": {
                          "type": "string",
                          "pattern": "^[1-9][0-9]{0,19}$",
                          "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                        },
                        "username": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "checkedAt": {
                          "type": "string"
                        },
                        "evidence": {
                          "const": "public_profile"
                        }
                      },
                      "required": [
                        "xUserId",
                        "username",
                        "name",
                        "checkedAt",
                        "evidence"
                      ]
                    },
                    "provider": {
                      "type": "string",
                      "description": "Identifies the PumpGTM data source used for this check."
                    },
                    "sendsMessages": {
                      "const": false
                    }
                  },
                  "required": [
                    "status",
                    "user",
                    "provider",
                    "sendsMessages"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/x/eligibility": {
      "post": {
        "operationId": "checkXFollowerEligibility",
        "tags": [
          "Leads"
        ],
        "summary": "Check whether leads follow your account",
        "description": "Direction: the lead follows the connected account. Supply exactly one X identity per lead. Handles use direct relationship evidence. Numeric IDs use a bounded public follower snapshot: presence is true; absence is null, never a verified false. null means unknown, not eligible or ineligible. Provider errors can produce HTTP 200 with unknown individual results. Up to 100 leads; sequential work is time bounded, so small batches are preferable. Per-instance short cache may be reused; checkedAt is evidence time. No messages are sent.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "account": {
                    "type": "string",
                    "pattern": "^@?[A-Za-z0-9_]{1,15}$",
                    "description": "Public X handle, with optional @. Case-insensitive."
                  },
                  "leads": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "reference": {
                          "type": "string",
                          "maxLength": 200
                        },
                        "xUsername": {
                          "type": "string",
                          "pattern": "^@?[A-Za-z0-9_]{1,15}$",
                          "description": "Public X handle, with optional @. Case-insensitive."
                        },
                        "xUserId": {
                          "type": "string",
                          "pattern": "^[1-9][0-9]{0,19}$",
                          "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                        }
                      },
                      "required": [],
                      "additionalProperties": false,
                      "oneOf": [
                        {
                          "required": [
                            "xUsername"
                          ]
                        },
                        {
                          "required": [
                            "xUserId"
                          ]
                        }
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 100
                  }
                },
                "required": [
                  "account",
                  "leads"
                ],
                "additionalProperties": false
              },
              "example": {
                "account": "mastra",
                "leads": [
                  {
                    "reference": "crm-123",
                    "xUsername": "example_handle"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "type": "string"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "reference": {
                            "type": "string"
                          },
                          "xUsername": {
                            "type": "string"
                          },
                          "xUserId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^[1-9][0-9]{0,19}$",
                                "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "followsAccount": {
                            "anyOf": [
                              {
                                "type": "boolean"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "checkedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "reason": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "evidence": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "xUserId",
                          "followsAccount",
                          "checkedAt",
                          "reason",
                          "evidence"
                        ]
                      }
                    },
                    "provider": {
                      "type": "string",
                      "description": "Identifies the PumpGTM data source used for this check."
                    },
                    "sendsMessages": {
                      "const": false
                    }
                  },
                  "required": [
                    "account",
                    "results",
                    "provider",
                    "sendsMessages"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/enrich": {
      "post": {
        "operationId": "enrichLeadIdentities",
        "tags": [
          "Leads"
        ],
        "summary": "Bridge emails or LinkedIn URLs to X identities",
        "description": "Up to 20 leads, each with one email or one public LinkedIn profile URL. Emails resolve to a LinkedIn identity first; only exact, source-governed public profile links then bridge LinkedIn to X. No name matching or fuzzy identity guesses. Results may be unavailable per lead; nothing is enrolled or sent.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leads": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "reference": {
                          "type": "string",
                          "maxLength": 200
                        },
                        "email": {
                          "type": "string",
                          "format": "email",
                          "maxLength": 320
                        },
                        "linkedinUrl": {
                          "type": "string",
                          "maxLength": 1500,
                          "description": "Public linkedin.com/in/... profile URL."
                        }
                      },
                      "required": [],
                      "additionalProperties": false,
                      "oneOf": [
                        {
                          "required": [
                            "email"
                          ]
                        },
                        {
                          "required": [
                            "linkedinUrl"
                          ]
                        }
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 20
                  }
                },
                "required": [
                  "leads"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/signals": {
      "get": {
        "operationId": "listSignalTypes",
        "tags": [
          "People search"
        ],
        "summary": "Discover Signals API availability",
        "description": "Lists available event types and coming-soon roadmap categories. Only available types can be read.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/signals/events": {
      "post": {
        "operationId": "listSignalEvents",
        "tags": [
          "People search"
        ],
        "summary": "Read events for an available signal type",
        "description": "Read-only shared-index developer preview. No Energy charged or paid collection. Stable event IDs, workspace/filter-bound cursors. start=now bootstraps future observations; recent reads up to 30 days. Cursor expires after 7 days. Collection is demand-driven; no coverage or cadence guarantee.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "const": "hiring.job_observed"
                  },
                  "filters": {
                    "type": "object",
                    "properties": {
                      "roles": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 2,
                          "maxLength": 100
                        },
                        "minItems": 1,
                        "maxItems": 10
                      },
                      "companyDomains": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 253
                        },
                        "minItems": 1,
                        "maxItems": 20
                      },
                      "minHeadcount": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "maxHeadcount": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "required": [],
                    "additionalProperties": false
                  },
                  "cursor": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 3000
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "start": {
                    "enum": [
                      "now",
                      "recent"
                    ],
                    "default": "recent"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 50
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Expired cursor; bootstrap again and deduplicate event IDs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request larger than 8 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Index temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/people/enrich": {
      "post": {
        "operationId": "enrichPerson",
        "tags": [
          "People search"
        ],
        "summary": "Enrich one person by email or LinkedIn URL",
        "description": "Send exactly one of email or linkedin; an email is matched to a LinkedIn profile first. Returns { id, person, missing?, energyUsed }. person is null, and nothing is charged, when nobody matches or the profile found is someone else's; otherwise name, title, headline, location, company {name, domain}, linkedin, x, workEmail {address, matchesCompanyDomain, verification {status, method, mailProvider, summary}}, and connections when any are observed. find adds paid extras: x (their X account, only with public evidence it is theirs) and work_email. A requested extra that did not come back appears in missing with a reason. Energy-priced on metered workspaces (402 when exhausted, nothing charged). Request body is limited to 4 KB (413). Nothing is sent. Send leadId (one of your own leads, the same person) with find [\"work_email\"] to save the found email on that lead when it has none; lead.email reports attached, lead_has_email, different_person, email_on_another_lead or no_email.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "maxLength": 320,
                    "description": "Email address to match to a LinkedIn profile. Omit when sending linkedin."
                  },
                  "linkedin": {
                    "type": "string",
                    "maxLength": 1500,
                    "description": "Public linkedin.com/in/... profile URL. Omit when sending email."
                  },
                  "find": {
                    "type": "array",
                    "items": {
                      "enum": [
                        "x",
                        "work_email"
                      ]
                    },
                    "maxItems": 2,
                    "default": []
                  },
                  "leadId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Your own lead to receive the found work email. It must be the same person and have no email."
                  }
                },
                "required": [],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "energy_exhausted: this metered workspace has no Energy left for the action; nothing changed. Follow topUpUrl.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "leadId is not a lead in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request body larger than 4 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/x/plays": {
      "get": {
        "operationId": "listXPlays",
        "tags": [
          "Manual review"
        ],
        "summary": "Discover X Plays and their revisions",
        "description": "Use reviewApiEnabled to identify Plays supporting candidate review, import, lookup and enrollment. Plays must be explicitly enabled for review APIs. Autopilot Plays cannot use manual import/enrollment.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plays": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "status": {
                            "enum": [
                              "active",
                              "paused",
                              "archived"
                            ]
                          },
                          "revision": {
                            "type": "integer",
                            "minimum": 1,
                            "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan."
                          },
                          "sequenceId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "accountUserId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^[1-9][0-9]{0,19}$",
                                "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "reviewApiEnabled": {
                            "type": "boolean"
                          },
                          "autopilot": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "status",
                          "revision",
                          "sequenceId",
                          "accountUserId",
                          "reviewApiEnabled",
                          "autopilot"
                        ]
                      }
                    }
                  },
                  "required": [
                    "plays"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/plays/{id}/candidates": {
      "get": {
        "operationId": "listPlayCandidates",
        "tags": [
          "Manual review"
        ],
        "summary": "Page through review candidates",
        "description": "Saved review candidates, not evidence of a current follow relationship. Returns Play and sequence revisions for guarded enrollment. Cursor paging covers all batches.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            }
          },
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Pass nextCursor from the previous response until null."
          },
          {
            "name": "filter",
            "in": "query",
            "schema": {
              "enum": [
                "all",
                "unreviewed",
                "good_fit",
                "not_a_good_fit"
              ],
              "default": "all"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "counts": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "unreviewed": {
                          "type": "integer"
                        },
                        "goodFit": {
                          "type": "integer"
                        },
                        "notAGoodFit": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "total",
                        "unreviewed",
                        "goodFit",
                        "notAGoodFit"
                      ]
                    },
                    "candidates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "xUserId": {
                            "type": "string",
                            "pattern": "^[1-9][0-9]{0,19}$",
                            "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                          },
                          "username": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "enum": [
                              "proposed",
                              "approved",
                              "imported",
                              "rejected"
                            ]
                          },
                          "review": {
                            "anyOf": [
                              {
                                "type": "object"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "xUserId",
                          "username",
                          "name",
                          "status",
                          "review"
                        ]
                      }
                    },
                    "nextCursor": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "uuid"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "play": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "revision": {
                          "type": "integer",
                          "minimum": 1,
                          "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan."
                        },
                        "status": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "revision",
                        "status"
                      ]
                    },
                    "sequence": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "name": {
                              "type": "string"
                            },
                            "revision": {
                              "type": "integer",
                              "minimum": 1,
                              "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan."
                            },
                            "status": {
                              "type": "string"
                            },
                            "approved": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "id",
                            "name",
                            "revision",
                            "status",
                            "approved"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "reviewUrl": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "counts",
                    "candidates",
                    "nextCursor",
                    "play",
                    "sequence",
                    "reviewUrl"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/plays/{id}/candidates/lookup": {
      "get": {
        "operationId": "lookupPlayCandidate",
        "tags": [
          "Manual review"
        ],
        "summary": "Find one existing candidate by X identity",
        "description": "Single-identity form of the POST lookup: pass xUserId or username as a query parameter. Exact lookup across all saved Play batches; ambiguous matches return 409. Does not check a live follower relationship.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "xUserId",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$",
              "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
            }
          },
          {
            "name": "username",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^@?[A-Za-z0-9_]{1,15}$",
              "description": "Public X handle, with optional @. Case-insensitive."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "exists": {
                      "type": "boolean"
                    },
                    "candidate": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "xUserId": {
                              "type": "string",
                              "pattern": "^[1-9][0-9]{0,19}$",
                              "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                            },
                            "username": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "name": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "status": {
                              "enum": [
                                "proposed",
                                "approved",
                                "imported",
                                "rejected"
                              ]
                            },
                            "review": {
                              "anyOf": [
                                {
                                  "type": "object"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            }
                          },
                          "required": [
                            "id",
                            "xUserId",
                            "username",
                            "name",
                            "status",
                            "review"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "enrolledInPlay": {
                      "type": "boolean"
                    },
                    "currentFollowerStatus": {
                      "const": "unknown"
                    },
                    "existingLeads": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "sequenceId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "playId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "stage": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "sequenceId",
                          "playId",
                          "stage"
                        ]
                      }
                    }
                  },
                  "required": [
                    "exists",
                    "candidate",
                    "enrolledInPlay",
                    "currentFollowerStatus",
                    "existingLeads"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "lookupPlayCandidates",
        "tags": [
          "Manual review"
        ],
        "summary": "Find existing candidates by X identity",
        "description": "Exact identity lookup across all saved Play batches. Each identity requires xUserId OR username. Ambiguous matches return 409; use numeric IDs or the candidate list. This endpoint does not check a live follower relationship.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "identities": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "xUserId": {
                          "type": "string",
                          "pattern": "^[1-9][0-9]{0,19}$",
                          "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                        },
                        "username": {
                          "type": "string",
                          "pattern": "^@?[A-Za-z0-9_]{1,15}$",
                          "description": "Public X handle, with optional @. Case-insensitive."
                        }
                      },
                      "required": [],
                      "additionalProperties": false,
                      "oneOf": [
                        {
                          "required": [
                            "xUserId"
                          ]
                        },
                        {
                          "required": [
                            "username"
                          ]
                        }
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 200
                  }
                },
                "required": [
                  "identities"
                ],
                "additionalProperties": false
              },
              "example": {
                "identities": [
                  {
                    "xUserId": "123456789"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "playId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "exists": {
                            "type": "boolean"
                          },
                          "candidate": {
                            "anyOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "xUserId": {
                                    "type": "string",
                                    "pattern": "^[1-9][0-9]{0,19}$",
                                    "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                                  },
                                  "username": {
                                    "anyOf": [
                                      {
                                        "type": "string"
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  },
                                  "name": {
                                    "anyOf": [
                                      {
                                        "type": "string"
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  },
                                  "status": {
                                    "enum": [
                                      "proposed",
                                      "approved",
                                      "imported",
                                      "rejected"
                                    ]
                                  },
                                  "review": {
                                    "anyOf": [
                                      {
                                        "type": "object"
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  }
                                },
                                "required": [
                                  "id",
                                  "xUserId",
                                  "username",
                                  "name",
                                  "status",
                                  "review"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "enrolledInPlay": {
                            "type": "boolean"
                          },
                          "currentFollowerStatus": {
                            "const": "unknown"
                          },
                          "existingLeads": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "format": "uuid"
                                },
                                "sequenceId": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "format": "uuid"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "playId": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "format": "uuid"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "stage": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "id",
                                "sequenceId",
                                "playId",
                                "stage"
                              ]
                            }
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "playId",
                    "results"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/plays/{id}/import": {
      "post": {
        "operationId": "importPlayCandidates",
        "tags": [
          "Manual review"
        ],
        "summary": "Import external leads for review",
        "description": "Requires an enabled, non-archived, manual-review Play. Resolve known handles first, then submit numeric IDs. Names are caller-provided display labels, not verified identity evidence. The operation is atomic: 1–100 unique IDs. requestId is scoped to workspace + Play; retry the exact same normalized payload for the stored result. Reusing it with changed inputs returns 409. Existing candidates retain their review state. Import does not verify followers, enroll, change sequence status or send. Duplicate candidate records produce 409.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requestId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$"
                  },
                  "expectedRevision": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan."
                  },
                  "leads": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "xUserId": {
                          "type": "string",
                          "pattern": "^[1-9][0-9]{0,19}$",
                          "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                        },
                        "name": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200
                        },
                        "reference": {
                          "type": "string",
                          "maxLength": 200
                        }
                      },
                      "required": [
                        "xUserId"
                      ],
                      "additionalProperties": false
                    },
                    "minItems": 1,
                    "maxItems": 100
                  }
                },
                "required": [
                  "requestId",
                  "expectedRevision",
                  "leads"
                ],
                "additionalProperties": false
              },
              "example": {
                "requestId": "crm-import-20261003-001",
                "expectedRevision": 1,
                "leads": [
                  {
                    "xUserId": "123456789",
                    "reference": "crm-123"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "playId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "batchId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "requestId": {
                      "type": "string"
                    },
                    "replayed": {
                      "type": "boolean"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "xUserId": {
                            "type": "string",
                            "pattern": "^[1-9][0-9]{0,19}$",
                            "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                          },
                          "reference": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "candidateId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "result": {
                            "enum": [
                              "imported",
                              "existing_candidate"
                            ]
                          }
                        },
                        "required": [
                          "xUserId",
                          "reference",
                          "candidateId",
                          "result"
                        ]
                      }
                    },
                    "enrolled": {
                      "const": false
                    },
                    "sendsMessages": {
                      "const": false
                    }
                  },
                  "required": [
                    "playId",
                    "batchId",
                    "requestId",
                    "replayed",
                    "results",
                    "enrolled",
                    "sendsMessages"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/plays/{id}/enroll": {
      "post": {
        "operationId": "enrollPlayCandidates",
        "tags": [
          "Manual review"
        ],
        "summary": "Approve candidates and enroll through the existing engine",
        "description": "Mutating action: marks selected candidates good fit and queues newly enrolled leads. Requires exact Play and sequence revisions and the Play's own connected sender/sequence. An active eligible sequence can send on its next engine run. Does not activate, approve or change the sequence itself. Existing leads (including stopped/replied leads) keep their original state and sequence. Repeating a completed good-fit review returns already_reviewed; conflicting review decisions return 409. POST /plays/{id}/leads with this same candidateIds body does the same.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedRevision": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan."
                  },
                  "sequenceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "sequenceRevision": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan."
                  },
                  "candidateIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "minItems": 1,
                    "maxItems": 200,
                    "uniqueItems": true
                  }
                },
                "required": [
                  "expectedRevision",
                  "sequenceId",
                  "sequenceRevision",
                  "candidateIds"
                ],
                "additionalProperties": false
              },
              "example": {
                "expectedRevision": 1,
                "sequenceId": "00000000-0000-4000-8000-000000000001",
                "sequenceRevision": 1,
                "candidateIds": [
                  "00000000-0000-4000-8000-000000000002"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "candidateId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "result": {
                            "enum": [
                              "enrolled",
                              "existing_lead",
                              "already_reviewed",
                              "rejected"
                            ]
                          },
                          "leadId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "candidateId",
                          "result",
                          "leadId"
                        ]
                      }
                    },
                    "sequenceStatus": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "sequenceStatusChanged": {
                      "const": false
                    },
                    "reviewUrl": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "results",
                    "sequenceStatus",
                    "sequenceStatusChanged",
                    "reviewUrl"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/x/actions": {
      "post": {
        "operationId": "performXAction",
        "tags": [
          "Leads"
        ],
        "summary": "Follow, like or repost as a connected account",
        "description": "One write as a connected X account: follow a profile URL or @handle, or like/repost a post URL. Never sends a DM or writes a post. Each successful write is one activity row and one Energy charge on metered workspaces (402 when exhausted). Requires the X channel; 409 x_not_connected when the account is not connected.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "enum": [
                      "follow",
                      "like",
                      "repost"
                    ]
                  },
                  "target": {
                    "type": "string",
                    "description": "Profile URL or @handle for follow; post URL for like and repost."
                  },
                  "as": {
                    "type": "string",
                    "pattern": "^@?[A-Za-z0-9_]{1,15}$",
                    "description": "Connected account to act as; defaults to the workspace's account."
                  }
                },
                "required": [
                  "action",
                  "target"
                ]
              },
              "example": {
                "action": "follow",
                "target": "@example_handle"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "action": {
                      "type": "string"
                    },
                    "as": {
                      "type": "string"
                    },
                    "username": {
                      "type": "string"
                    },
                    "postId": {
                      "type": "string"
                    },
                    "done": {
                      "const": true
                    }
                  },
                  "required": [
                    "action",
                    "as",
                    "done"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "energy_exhausted: this metered workspace has no Energy left for the action; nothing changed. Follow topUpUrl.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/x/leads/{id}": {
      "get": {
        "operationId": "getXLeadStatus",
        "tags": [
          "Leads"
        ],
        "summary": "Read one lead's saved progress",
        "description": "Tenant-owned X lead only. Stage/milestones are saved observations, not a live provider probe. automationStopped means the sequence is done/stopped; it does not distinguish normal completion from a manual stop.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lead": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "xUserId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]{0,19}$",
                              "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "username": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "accountUserId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]{0,19}$",
                              "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "playId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "sequenceId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "stage": {
                          "type": "string"
                        },
                        "automationStopped": {
                          "type": "boolean"
                        },
                        "currentStep": {
                          "type": "integer"
                        },
                        "nextActionAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "followedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "followedBackAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "messagedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "repliedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "optedOutAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "deliveryGuaranteed": {
                          "const": false
                        }
                      },
                      "required": [
                        "id",
                        "xUserId",
                        "username",
                        "accountUserId",
                        "playId",
                        "sequenceId",
                        "stage",
                        "automationStopped",
                        "currentStep",
                        "nextActionAt",
                        "followedAt",
                        "followedBackAt",
                        "messagedAt",
                        "repliedAt",
                        "optedOutAt",
                        "deliveryGuaranteed"
                      ]
                    }
                  },
                  "required": [
                    "lead"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/x/leads/{id}/stop": {
      "post": {
        "operationId": "stopXLead",
        "tags": [
          "Leads"
        ],
        "summary": "Stop this lead's future automation",
        "description": "Idempotent stop using the existing removal controls. Stops all sequence lanes for this lead, preserving contacted history; uncontacted queued leads become skipped. Available even after X is disabled. Does not recall dispatched actions, permanently suppress the identity, or delete history.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "lead": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "xUserId": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "pattern": "^[1-9][0-9]{0,19}$",
                                  "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "username": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "accountUserId": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "pattern": "^[1-9][0-9]{0,19}$",
                                  "description": "Numeric X user ID as a string. Never convert it to a JavaScript number."
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "playId": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "uuid"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "sequenceId": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "uuid"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "stage": {
                              "type": "string"
                            },
                            "automationStopped": {
                              "type": "boolean"
                            },
                            "currentStep": {
                              "type": "integer"
                            },
                            "nextActionAt": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "followedAt": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "followedBackAt": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "messagedAt": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "repliedAt": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "optedOutAt": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "deliveryGuaranteed": {
                              "const": false
                            }
                          },
                          "required": [
                            "id",
                            "xUserId",
                            "username",
                            "accountUserId",
                            "playId",
                            "sequenceId",
                            "stage",
                            "automationStopped",
                            "currentStep",
                            "nextActionAt",
                            "followedAt",
                            "followedBackAt",
                            "messagedAt",
                            "repliedAt",
                            "optedOutAt",
                            "deliveryGuaranteed"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "scope": {
                      "const": "lead_automation"
                    },
                    "permanentSuppression": {
                      "const": false
                    },
                    "note": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "lead",
                    "scope",
                    "permanentSuppression",
                    "note"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sequences": {
      "get": {
        "operationId": "listSequences",
        "tags": [
          "Sequences"
        ],
        "summary": "List existing sequences",
        "description": "Read tenant-owned sequences, exact lead counts, executionModel and routing. Compact steps use index/message and retain next, condition and sendIf. GET /sequences/{id} returns the editable stepIndex/messageTmpl shape and exact revision; read it before PUT so graph edges and conditions survive a full replacement. Create with POST /sequences, replace with PUT /sequences/{id}, and pause or resume with PATCH /sequences/{id}/status.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sequences": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "revision": {
                            "type": "integer"
                          },
                          "approvedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "approvedRevision": {
                            "anyOf": [
                              {
                                "type": "integer"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "executionBlockReason": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "executionModel": {
                            "enum": [
                              "linear",
                              "tracks",
                              "graph"
                            ],
                            "description": "linear (default on create): up to 20 ordered steps; X steps cannot mix other channels. tracks: up to 20 steps in parallel LinkedIn, email and X lanes. graph: up to 30 nodes mixing those channels with next edges and branch conditions; connect can appear anywhere, at most once per path. In a graph, a LinkedIn message or endorsement must come after a connection request and an 'Accepted?' (linkedin_accepted) or 'Already connected?' (linkedin_first_degree) Yes path; view, like and comment need no connection. A comment someone can reach before the flow's connection request needs the linkedin_comment_before_connect feature (refused otherwise, changing nothing) and is passed over for people already connected or sent a request. Instagram DMs require their own linear sequence. Omission on edit keeps the saved model."
                          },
                          "leadCount": {
                            "type": "integer"
                          },
                          "channels": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "steps": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "index": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "kind": {
                                  "enum": [
                                    "connect",
                                    "message",
                                    "engage",
                                    "email",
                                    "x_dm",
                                    "x_engage",
                                    "instagram_dm",
                                    "branch"
                                  ]
                                },
                                "delayDays": {
                                  "type": "integer"
                                },
                                "subject": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "message": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "next": {
                                  "anyOf": [
                                    {
                                      "oneOf": [
                                        {
                                          "type": "object",
                                          "properties": {
                                            "next": {
                                              "anyOf": [
                                                {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 29
                                                },
                                                {
                                                  "type": "null"
                                                }
                                              ]
                                            }
                                          },
                                          "required": [
                                            "next"
                                          ],
                                          "additionalProperties": false
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "yes": {
                                              "anyOf": [
                                                {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 29
                                                },
                                                {
                                                  "type": "null"
                                                }
                                              ]
                                            },
                                            "no": {
                                              "anyOf": [
                                                {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 29
                                                },
                                                {
                                                  "type": "null"
                                                }
                                              ]
                                            }
                                          },
                                          "required": [
                                            "yes",
                                            "no"
                                          ],
                                          "additionalProperties": false
                                        }
                                      ],
                                      "description": "graph only: an action uses { next: stepIndex }, a branch uses { yes: stepIndex, no: stepIndex }. A null target ends that path, for example { next: null }. Omitting an action's next object or passing top-level next: null defaults to the next array step; preserve returned edges when editing. All nodes must be reachable from step 0 and cycles are forbidden."
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "condition": {
                                  "anyOf": [
                                    {
                                      "enum": [
                                        "linkedin_accepted",
                                        "x_followed_back",
                                        "has_email",
                                        "linkedin_first_degree"
                                      ],
                                      "description": "branch only: linkedin_accepted and x_followed_back wait up to delayDays for yes, otherwise take no. has_email and linkedin_first_degree evaluate the person's available identity or connection state."
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "sendIf": {
                                  "anyOf": [
                                    {
                                      "enum": [
                                        "followed_back",
                                        "not_followed_back"
                                      ]
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "attachments": {
                                  "type": "array",
                                  "maxItems": 5,
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "string",
                                        "format": "uuid"
                                      },
                                      "name": {
                                        "type": "string"
                                      },
                                      "size": {
                                        "type": "integer",
                                        "minimum": 1
                                      }
                                    },
                                    "required": [
                                      "id",
                                      "name",
                                      "size"
                                    ],
                                    "additionalProperties": false
                                  },
                                  "description": "Existing uploaded attachment references for LinkedIn message steps. Preserve returned references when editing."
                                },
                                "actions": {
                                  "anyOf": [
                                    {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "additionalProperties": true
                                      }
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "variants": {
                                  "anyOf": [
                                    {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "additionalProperties": true
                                      }
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "tool": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "additionalProperties": true
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "index",
                                "kind",
                                "delayDays",
                                "subject",
                                "message",
                                "next",
                                "condition",
                                "sendIf",
                                "attachments",
                                "actions",
                                "variants",
                                "tool"
                              ]
                            }
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "status",
                          "revision",
                          "approvedAt",
                          "approvedRevision",
                          "executionBlockReason",
                          "executionModel",
                          "leadCount",
                          "channels",
                          "steps"
                        ],
                        "description": "Compact list item with executionModel and step next/condition/sendIf. Steps still use index and message. Read GET /sequences/{id} for the editable field names and exact revision before PUT."
                      }
                    }
                  },
                  "required": [
                    "sequences"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createSequence",
        "tags": [
          "Sequences"
        ],
        "summary": "Create a complete sequence",
        "description": "Save a complete sequence with the same step and approval rules as the PumpGTM agent tools: up to 30 graph steps or 20 linear/tracks steps. Your request is the approval: with a workspace or partner key the sequence is approved and live when this returns (live: true). Nothing is sent until people are added; sends retain working hours, account limits and reply stops. X steps need x_channel. Graph reply safety is automatic across previously contacted email, LinkedIn and X conversations, independently of xThreadCheck; unavailable reply evidence holds the action. requestId (8-120 characters, first alphanumeric) replays the stored result with replayed: true for the same body; 409 sequence_create_request_conflict for changed content; 409 sequence_step_limit_exceeded for the model limit or sequence_steps_invalid with detail for invalid steps.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requestId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$",
                    "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160
                  },
                  "steps": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "stepIndex": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 29,
                          "description": "Optional zero-based position; when supplied it must match the array index. Graphs allow indices 0–29; linear/tracks allow 0–19."
                        },
                        "kind": {
                          "enum": [
                            "connect",
                            "message",
                            "engage",
                            "email",
                            "x_dm",
                            "x_engage",
                            "instagram_dm",
                            "branch"
                          ]
                        },
                        "delayDays": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 30,
                          "description": "linear: after the previous step, with acceptance required after connect. tracks: after the previous step in that channel's lane. graph: delay on entering an action node, or the waiting branch's condition window; the initial step starts immediately."
                        },
                        "subject": {
                          "anyOf": [
                            {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 200,
                              "description": "Email steps only; required on the first email. In a graph, it is required if any incoming path has not already sent an email."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "messageTmpl": {
                          "anyOf": [
                            {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 8000,
                              "description": "Required for email, x_dm and instagram_dm; a LinkedIn message may instead put text on every variant. {{firstName}} {{fullName}} {{company}} {{title}} render on every channel."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "sendIf": {
                          "anyOf": [
                            {
                              "enum": [
                                "followed_back",
                                "not_followed_back"
                              ],
                              "description": "x_dm only: DM only people who followed back after an earlier x_engage follow, or only those who did not."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "next": {
                          "anyOf": [
                            {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "properties": {
                                    "next": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 29
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ]
                                    }
                                  },
                                  "required": [
                                    "next"
                                  ],
                                  "additionalProperties": false
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "yes": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 29
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ]
                                    },
                                    "no": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 29
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ]
                                    }
                                  },
                                  "required": [
                                    "yes",
                                    "no"
                                  ],
                                  "additionalProperties": false
                                }
                              ],
                              "description": "graph only: an action uses { next: stepIndex }, a branch uses { yes: stepIndex, no: stepIndex }. A null target ends that path, for example { next: null }. Omitting an action's next object or passing top-level next: null defaults to the next array step; preserve returned edges when editing. All nodes must be reachable from step 0 and cycles are forbidden."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "condition": {
                          "anyOf": [
                            {
                              "enum": [
                                "linkedin_accepted",
                                "x_followed_back",
                                "has_email",
                                "linkedin_first_degree"
                              ],
                              "description": "branch only: linkedin_accepted and x_followed_back wait up to delayDays for yes, otherwise take no. has_email and linkedin_first_degree evaluate the person's available identity or connection state."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "attachments": {
                          "type": "array",
                          "maxItems": 5,
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "size": {
                                "type": "integer",
                                "minimum": 1
                              }
                            },
                            "required": [
                              "id",
                              "name",
                              "size"
                            ],
                            "additionalProperties": false
                          },
                          "description": "Existing uploaded attachment references for LinkedIn message steps. Preserve returned references when editing."
                        },
                        "actions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "type": {
                                "enum": [
                                  "follow",
                                  "unfollow",
                                  "view_profile",
                                  "like_last_post",
                                  "endorse_first_skill",
                                  "comment_last_post"
                                ]
                              },
                              "count": {
                                "type": "integer",
                                "minimum": 1,
                                "maximum": 3,
                                "description": "like_last_post only: how many of their newest posts to react to. In a step with comment_last_post the reaction goes once on the post the comment answers."
                              },
                              "reaction": {
                                "enum": [
                                  "like",
                                  "celebrate",
                                  "support",
                                  "love",
                                  "insightful",
                                  "funny"
                                ]
                              },
                              "guidance": {
                                "type": "string",
                                "maxLength": 1250,
                                "description": "comment_last_post only: optional guidance for the comment PumpGTM writes for each person's latest original post. Every comment waits for the customer's approval in the app before it posts."
                              },
                              "text": {
                                "type": "string",
                                "maxLength": 1250,
                                "deprecated": true,
                                "description": "Older name for guidance on comment_last_post; read as guidance, never posted as written."
                              }
                            },
                            "required": [
                              "type"
                            ],
                            "additionalProperties": false
                          },
                          "maxItems": 10,
                          "description": "Required and non-empty for engage or x_engage; x_engage supports follow and unfollow only."
                        },
                        "variants": {
                          "anyOf": [
                            {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 5
                                  },
                                  "weight": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "maximum": 10000
                                  },
                                  "messageTmpl": {
                                    "type": "string",
                                    "maxLength": 2000
                                  }
                                },
                                "required": [
                                  "key",
                                  "weight"
                                ],
                                "additionalProperties": false
                              },
                              "maxItems": 10
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "tool": {
                          "anyOf": [
                            {
                              "type": "object",
                              "additionalProperties": true,
                              "description": "LinkedIn message steps take either tool; email and X DM steps take only customer_input. Either { kind: \"customer_input\", tokens: [\"video_url\"] } (up to 5 lowercase tokens the customer supplies per person through POST /leads/{id}/input; LinkedIn message, email, X DM and Instagram DM steps may add attachment: { key: \"personal_file\" } for a file per person (email: one document, image or MP4; X: one image or MP4 video), in which case tokens may be empty) or a personalised video generated by the connected video tool: { kind: \"sendspark\", params, outputToken?: \"video_url\", timeoutHours?: 1-168, fallback?: \"send_without\" | \"skip_step\" }.",
                              "properties": {
                                "kind": {
                                  "enum": [
                                    "customer_input",
                                    "sendspark"
                                  ]
                                }
                              },
                              "required": [
                                "kind"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "kind",
                        "delayDays"
                      ],
                      "additionalProperties": false
                    },
                    "minItems": 1,
                    "maxItems": 30,
                    "description": "Complete replacement, not a patch. Runtime limit: 30 steps for graph; 20 for linear/tracks. With LinkedIn, linear starts with connect and tracks puts connect first in the LinkedIn lane. Graphs may start with email, X or LinkedIn engagement and do not require connect first, but a LinkedIn message or endorsement must come after a connection request and an 'Accepted?' (linkedin_accepted) or 'Already connected?' (linkedin_first_degree) Yes path; view, like and comment need no connection. To like and comment on someone's newest post before the connection request, start with an engage step [like_last_post, comment_last_post] whose next is connect with delayDays 1: the request goes out a day after the comment posts or is skipped. Retain next, condition, sendIf, attachments and other unchanged fields from the detailed read."
                  },
                  "executionModel": {
                    "enum": [
                      "linear",
                      "tracks",
                      "graph"
                    ],
                    "description": "linear (default on create): up to 20 ordered steps; X steps cannot mix other channels. tracks: up to 20 steps in parallel LinkedIn, email and X lanes. graph: up to 30 nodes mixing those channels with next edges and branch conditions; connect can appear anywhere, at most once per path. In a graph, a LinkedIn message or endorsement must come after a connection request and an 'Accepted?' (linkedin_accepted) or 'Already connected?' (linkedin_first_degree) Yes path; view, like and comment need no connection. A comment someone can reach before the flow's connection request needs the linkedin_comment_before_connect feature (refused otherwise, changing nothing) and is passed over for people already connected or sent a request. Instagram DMs require their own linear sequence. Omission on edit keeps the saved model."
                  },
                  "xThreadCheck": {
                    "type": "boolean",
                    "description": "Workspace-wide optional X prior-conversation check (5 Energy per DM instead of 0.6), default off. Omit to retain the saved setting. Automatic graph reply safety is separate and always checks previously contacted email, LinkedIn and X conversations before further graph outreach; false does not disable it. A human reply stops the flow; unavailable evidence holds it."
                  }
                },
                "required": [
                  "name",
                  "steps"
                ],
                "additionalProperties": false
              },
              "example": {
                "name": "Founders in fintech",
                "steps": [
                  {
                    "kind": "connect",
                    "delayDays": 0
                  },
                  {
                    "kind": "message",
                    "delayDays": 1,
                    "messageTmpl": "Hi {{firstName}}, thanks for connecting."
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sequence": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "Full sequence: { id, name, status, revision, approvedAt, approvedRevision, executionBlockReason, executionModel, leadCount, channels, steps: [{ stepIndex, kind, delayDays, subject, messageTmpl, actions, variants, tool, attachments, sendIf, next, condition }], updatedAt }. Preserve next, condition and sendIf on full replacement; absent routing/gating values are null. Steps use the request names stepIndex/messageTmpl, unlike the compact list's index/message."
                    },
                    "reviewUrl": {
                      "type": "string"
                    },
                    "live": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "sequence",
                    "reviewUrl",
                    "live"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sequences/{id}": {
      "get": {
        "operationId": "getSequence",
        "tags": [
          "Sequences"
        ],
        "summary": "Read one sequence with its revision",
        "description": "One owned sequence with executionModel, exact revision and the full editable steps (stepIndex, messageTmpl, next, condition, sendIf and other saved fields). Read it before PUT and preserve unchanged graph edges and conditions. 404 not_found (resource sequence) outside this workspace.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sequence": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "Full sequence: { id, name, status, revision, approvedAt, approvedRevision, executionBlockReason, executionModel, leadCount, channels, steps: [{ stepIndex, kind, delayDays, subject, messageTmpl, actions, variants, tool, attachments, sendIf, next, condition }], updatedAt }. Preserve next, condition and sendIf on full replacement; absent routing/gating values are null. Steps use the request names stepIndex/messageTmpl, unlike the compact list's index/message."
                    }
                  },
                  "required": [
                    "sequence"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "replaceSequence",
        "tags": [
          "Sequences"
        ],
        "summary": "Replace a sequence's steps as a new revision",
        "description": "Complete revisioned replacement: read GET /sequences/{id}, then send its full editable step list with expectedRevision equal to that exact revision. Preserve next, condition, sendIf and every unchanged field; compact index/message fields are not accepted. With a customer credential the new revision is re-approved and returns to its previous status (active stays active, paused stays paused, a draft goes live). Omitted executionModel keeps the saved model; changing models requires no execution progress. Graphs allow 30 steps; linear/tracks allow 20. Once any graph lead has left step 0, step count, kinds, edges and conditions cannot change; copy and delays may still be edited without moving lead cursors. Once someone still in outreach may have received a step (an earlier linear step, an earlier step in their lane, a graph node leading to their current node, or the step they are being sent right now), that step must keep identical content, or the edit is refused with sequence_edit_would_repeat; a linear step may still be removed when every remaining step is unchanged. Linear people move past every step they may have received, matched by exact content. 409 with nothing changed: sequence_revision_conflict, sequence_edit_request_conflict, sequence_has_progress, sequence_edit_would_repeat, archived_sequence_is_read_only, sequence_must_be_draft, sequence_step_limit_exceeded, sequence_steps_invalid; update.currentRevision is included where known. Re-read on a revision conflict; never retry by silently overwriting newer content.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requestId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$",
                    "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request."
                  },
                  "expectedRevision": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160
                  },
                  "steps": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "stepIndex": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 29,
                          "description": "Optional zero-based position; when supplied it must match the array index. Graphs allow indices 0–29; linear/tracks allow 0–19."
                        },
                        "kind": {
                          "enum": [
                            "connect",
                            "message",
                            "engage",
                            "email",
                            "x_dm",
                            "x_engage",
                            "instagram_dm",
                            "branch"
                          ]
                        },
                        "delayDays": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 30,
                          "description": "linear: after the previous step, with acceptance required after connect. tracks: after the previous step in that channel's lane. graph: delay on entering an action node, or the waiting branch's condition window; the initial step starts immediately."
                        },
                        "subject": {
                          "anyOf": [
                            {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 200,
                              "description": "Email steps only; required on the first email. In a graph, it is required if any incoming path has not already sent an email."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "messageTmpl": {
                          "anyOf": [
                            {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 8000,
                              "description": "Required for email, x_dm and instagram_dm; a LinkedIn message may instead put text on every variant. {{firstName}} {{fullName}} {{company}} {{title}} render on every channel."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "sendIf": {
                          "anyOf": [
                            {
                              "enum": [
                                "followed_back",
                                "not_followed_back"
                              ],
                              "description": "x_dm only: DM only people who followed back after an earlier x_engage follow, or only those who did not."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "next": {
                          "anyOf": [
                            {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "properties": {
                                    "next": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 29
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ]
                                    }
                                  },
                                  "required": [
                                    "next"
                                  ],
                                  "additionalProperties": false
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "yes": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 29
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ]
                                    },
                                    "no": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 29
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ]
                                    }
                                  },
                                  "required": [
                                    "yes",
                                    "no"
                                  ],
                                  "additionalProperties": false
                                }
                              ],
                              "description": "graph only: an action uses { next: stepIndex }, a branch uses { yes: stepIndex, no: stepIndex }. A null target ends that path, for example { next: null }. Omitting an action's next object or passing top-level next: null defaults to the next array step; preserve returned edges when editing. All nodes must be reachable from step 0 and cycles are forbidden."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "condition": {
                          "anyOf": [
                            {
                              "enum": [
                                "linkedin_accepted",
                                "x_followed_back",
                                "has_email",
                                "linkedin_first_degree"
                              ],
                              "description": "branch only: linkedin_accepted and x_followed_back wait up to delayDays for yes, otherwise take no. has_email and linkedin_first_degree evaluate the person's available identity or connection state."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "attachments": {
                          "type": "array",
                          "maxItems": 5,
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "size": {
                                "type": "integer",
                                "minimum": 1
                              }
                            },
                            "required": [
                              "id",
                              "name",
                              "size"
                            ],
                            "additionalProperties": false
                          },
                          "description": "Existing uploaded attachment references for LinkedIn message steps. Preserve returned references when editing."
                        },
                        "actions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "type": {
                                "enum": [
                                  "follow",
                                  "unfollow",
                                  "view_profile",
                                  "like_last_post",
                                  "endorse_first_skill",
                                  "comment_last_post"
                                ]
                              },
                              "count": {
                                "type": "integer",
                                "minimum": 1,
                                "maximum": 3,
                                "description": "like_last_post only: how many of their newest posts to react to. In a step with comment_last_post the reaction goes once on the post the comment answers."
                              },
                              "reaction": {
                                "enum": [
                                  "like",
                                  "celebrate",
                                  "support",
                                  "love",
                                  "insightful",
                                  "funny"
                                ]
                              },
                              "guidance": {
                                "type": "string",
                                "maxLength": 1250,
                                "description": "comment_last_post only: optional guidance for the comment PumpGTM writes for each person's latest original post. Every comment waits for the customer's approval in the app before it posts."
                              },
                              "text": {
                                "type": "string",
                                "maxLength": 1250,
                                "deprecated": true,
                                "description": "Older name for guidance on comment_last_post; read as guidance, never posted as written."
                              }
                            },
                            "required": [
                              "type"
                            ],
                            "additionalProperties": false
                          },
                          "maxItems": 10,
                          "description": "Required and non-empty for engage or x_engage; x_engage supports follow and unfollow only."
                        },
                        "variants": {
                          "anyOf": [
                            {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 5
                                  },
                                  "weight": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "maximum": 10000
                                  },
                                  "messageTmpl": {
                                    "type": "string",
                                    "maxLength": 2000
                                  }
                                },
                                "required": [
                                  "key",
                                  "weight"
                                ],
                                "additionalProperties": false
                              },
                              "maxItems": 10
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "tool": {
                          "anyOf": [
                            {
                              "type": "object",
                              "additionalProperties": true,
                              "description": "LinkedIn message steps take either tool; email and X DM steps take only customer_input. Either { kind: \"customer_input\", tokens: [\"video_url\"] } (up to 5 lowercase tokens the customer supplies per person through POST /leads/{id}/input; LinkedIn message, email, X DM and Instagram DM steps may add attachment: { key: \"personal_file\" } for a file per person (email: one document, image or MP4; X: one image or MP4 video), in which case tokens may be empty) or a personalised video generated by the connected video tool: { kind: \"sendspark\", params, outputToken?: \"video_url\", timeoutHours?: 1-168, fallback?: \"send_without\" | \"skip_step\" }.",
                              "properties": {
                                "kind": {
                                  "enum": [
                                    "customer_input",
                                    "sendspark"
                                  ]
                                }
                              },
                              "required": [
                                "kind"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "kind",
                        "delayDays"
                      ],
                      "additionalProperties": false
                    },
                    "minItems": 1,
                    "maxItems": 30,
                    "description": "Complete replacement, not a patch. Runtime limit: 30 steps for graph; 20 for linear/tracks. With LinkedIn, linear starts with connect and tracks puts connect first in the LinkedIn lane. Graphs may start with email, X or LinkedIn engagement and do not require connect first, but a LinkedIn message or endorsement must come after a connection request and an 'Accepted?' (linkedin_accepted) or 'Already connected?' (linkedin_first_degree) Yes path; view, like and comment need no connection. To like and comment on someone's newest post before the connection request, start with an engage step [like_last_post, comment_last_post] whose next is connect with delayDays 1: the request goes out a day after the comment posts or is skipped. Retain next, condition, sendIf, attachments and other unchanged fields from the detailed read."
                  },
                  "executionModel": {
                    "enum": [
                      "linear",
                      "tracks",
                      "graph"
                    ],
                    "description": "linear (default on create): up to 20 ordered steps; X steps cannot mix other channels. tracks: up to 20 steps in parallel LinkedIn, email and X lanes. graph: up to 30 nodes mixing those channels with next edges and branch conditions; connect can appear anywhere, at most once per path. In a graph, a LinkedIn message or endorsement must come after a connection request and an 'Accepted?' (linkedin_accepted) or 'Already connected?' (linkedin_first_degree) Yes path; view, like and comment need no connection. A comment someone can reach before the flow's connection request needs the linkedin_comment_before_connect feature (refused otherwise, changing nothing) and is passed over for people already connected or sent a request. Instagram DMs require their own linear sequence. Omission on edit keeps the saved model."
                  },
                  "xThreadCheck": {
                    "type": "boolean",
                    "description": "Workspace-wide optional X prior-conversation check (5 Energy per DM instead of 0.6), default off. Omit to retain the saved setting. Automatic graph reply safety is separate and always checks previously contacted email, LinkedIn and X conversations before further graph outreach; false does not disable it. A human reply stops the flow; unavailable evidence holds it."
                  }
                },
                "required": [
                  "expectedRevision",
                  "steps"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "update": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "{ ok: true, replayed, sequence, live, change: { previousRevision, revision, currentRevision, previousStatus, nameChanged, stepCountBefore, stepCountAfter, changedStepIndexes, approvalInvalidated } }"
                    },
                    "reviewUrl": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "update",
                    "reviewUrl"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sequences/{id}/status": {
      "patch": {
        "operationId": "setSequenceStatus",
        "tags": [
          "Sequences"
        ],
        "summary": "Pause or resume an existing sequence",
        "description": "Affects every lead in this sequence. active may enable sending, subject to existing approval, billing, budget and provider controls. paused halts future sequence work; already dispatched actions cannot be recalled. Does not edit or approve content. 400 { error: \"status must be one of active, paused, draft\" } for any other value; 404 { error: \"sequence not found\" } outside this workspace; 409 { ok: false, error: sequence_approval_required | archived_sequence_is_read_only } when the change is refused.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "enum": [
                      "active",
                      "paused",
                      "draft"
                    ]
                  }
                },
                "required": [
                  "status"
                ]
              },
              "example": {
                "status": "paused"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "sequenceId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "previousStatus": {
                      "enum": [
                        "draft",
                        "active",
                        "paused",
                        "archived"
                      ]
                    },
                    "status": {
                      "enum": [
                        "active",
                        "paused",
                        "draft"
                      ]
                    }
                  },
                  "required": [
                    "ok",
                    "sequenceId",
                    "previousStatus",
                    "status"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "{ error: \"status must be one of active, paused, draft\" }",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "{ error: \"sequence not found\" }",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "{ ok: false, error: \"sequence_approval_required\" | \"archived_sequence_is_read_only\" }; nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sequences/{id}/leads": {
      "post": {
        "operationId": "addSequenceLeads",
        "tags": [
          "Leads"
        ],
        "summary": "Add people to a sequence",
        "description": "Queue people into one sequence. Nothing is sent in this call: people enter the paced engine and are contacted later inside working hours and account limits.\n\n**Choose a method**\n\n- `contacts`: 1 to 500 people, each with any mix of `linkedinUrl`, `email` and `xUsername`. Needs a connected LinkedIn account only when LinkedIn people go into a sequence with LinkedIn steps.\n- `manual`: 1 to 500 people with LinkedIn URLs. Always needs a connected LinkedIn account.\n- `csv`: CSV text with a header row, at most 500 rows. Always needs a connected LinkedIn account.\n- `sales_navigator`: a saved Sales Navigator list URL. Imports in the background; poll `GET /leads/imports/{batchId}`. Always needs a connected LinkedIn account.\n\n**Choose a sender**\n\nOptional `accountId` selects the connected LinkedIn sender for newly added LinkedIn people in all four methods. Email/X-only people keep their own channel routing. Omit it for automatic assignment. The selection belongs to this workspace, is retained across retries, and never changes an existing person's sender. Sales Navigator also uses it to fetch the list; older saved imports retain their original assignment behavior.\n\n**How `contacts` routes people**\n\n- Each person is queued only for the channels the sequence has steps for: connect steps are the LinkedIn lane, email steps the email lane, X DM or engage steps the X lane.\n- A person with no identity for any of the sequence's channels is counted in `invalidSkipped` and not added.\n- People already known by LinkedIn profile, email or X handle are counted in `duplicatesSkipped`.\n- X handles are at most 15 characters. An X-only person becomes sendable once their handle has been resolved to an X account, which happens automatically shortly after the add.\n- No paid lookups and no Energy charged.\n\n**Approval and replay**\n\n- Your request is the approval: a draft sequence is approved and started as part of the add. A paused sequence takes the people and stays paused.\n- `requestId` is optional. Reusing it with the same body replays the stored result (`reused: true`); reusing it with a different body is refused.\n- `expectedRevision` is optional on `contacts`. When given it must equal the sequence's current revision.\n\n**Refusals (409, nothing added)**\n\n`idempotency_conflict`, `sequence_not_active`, `sequence_not_ready`, `sequence_revision_conflict`, `lead_sender_unavailable`, `linkedin_not_connected` (partners: complete a hosted connect link first) and the `lead_import_csv_*` mapping refusals, which carry `details`.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "method": {
                        "const": "contacts"
                      },
                      "requestId": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$",
                        "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request."
                      },
                      "invitePriority": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 1000,
                        "description": "Optional, default 0, for everyone in this request. Higher priority people get their connection request before the rest of the workspace queue; nobody already queued is removed or demoted. Pacing, working hours, account limits and reply stops still apply."
                      },
                      "accountId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 160,
                        "description": "Optional LinkedIn sender: the public id from the partner LinkedIn accounts list or get_workspace channels.linkedin.data.senders.items. Legacy account-name IDs remain accepted. Must be connected in the selected workspace. Omit for automatic assignment; never reassigns existing leads. Sales Navigator uses an explicit selection for both fetching and sending."
                      },
                      "expectedRevision": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Optional. When given it must equal the sequence's current revision (409 sequence_revision_conflict otherwise); omitted means the current revision."
                      },
                      "leads": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "person": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 200
                            },
                            "company": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 200
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "title": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 200
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "linkedinUrl": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 500,
                                  "description": "Public LinkedIn /in/ profile URL."
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "email": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "email",
                                  "maxLength": 320
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "xUsername": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 500,
                                  "description": "X handle (with or without @) or x.com profile URL."
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            }
                          },
                          "required": [
                            "person"
                          ],
                          "additionalProperties": false
                        },
                        "minItems": 1,
                        "maxItems": 500,
                        "description": "1 to 500 people, each with at least one of linkedinUrl, email or xUsername. A person is queued only for the channels the sequence has steps for; someone with no identity for any of its channels is counted in invalidSkipped."
                      }
                    },
                    "required": [
                      "method",
                      "leads"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "method": {
                        "const": "manual"
                      },
                      "requestId": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$",
                        "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request."
                      },
                      "invitePriority": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 1000,
                        "description": "Optional, default 0, for everyone in this request. Higher priority people get their connection request before the rest of the workspace queue; nobody already queued is removed or demoted. Pacing, working hours, account limits and reply stops still apply."
                      },
                      "accountId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 160,
                        "description": "Optional LinkedIn sender: the public id from the partner LinkedIn accounts list or get_workspace channels.linkedin.data.senders.items. Legacy account-name IDs remain accepted. Must be connected in the selected workspace. Omit for automatic assignment; never reassigns existing leads. Sales Navigator uses an explicit selection for both fetching and sending."
                      },
                      "leads": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "linkedinUrl": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 500
                            },
                            "person": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 200
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "company": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 200
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "title": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 200
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "customFields": {
                              "type": "object",
                              "propertyNames": {
                                "pattern": "^[a-z][a-z0-9_]{0,39}$"
                              },
                              "additionalProperties": {
                                "type": "string",
                                "maxLength": 1000
                              },
                              "description": "Per-person values from your own list, keyed by a lowercase token such as personalized_message; written verbatim wherever a message uses {{personalized_message}}."
                            }
                          },
                          "required": [
                            "linkedinUrl"
                          ],
                          "additionalProperties": false
                        },
                        "minItems": 1,
                        "maxItems": 500
                      }
                    },
                    "required": [
                      "method",
                      "leads"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "method": {
                        "const": "csv"
                      },
                      "requestId": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$",
                        "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request."
                      },
                      "invitePriority": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 1000,
                        "description": "Optional, default 0, for everyone in this request. Higher priority people get their connection request before the rest of the workspace queue; nobody already queued is removed or demoted. Pacing, working hours, account limits and reply stops still apply."
                      },
                      "accountId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 160,
                        "description": "Optional LinkedIn sender: the public id from the partner LinkedIn accounts list or get_workspace channels.linkedin.data.senders.items. Legacy account-name IDs remain accepted. Must be connected in the selected workspace. Omit for automatic assignment; never reassigns existing leads. Sales Navigator uses an explicit selection for both fetching and sending."
                      },
                      "csvContent": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200000,
                        "description": "CSV with a header row; at most 500 rows and 100 columns. Person, LinkedIn URL, Company and Title columns are recognised by name."
                      },
                      "customColumns": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string",
                          "pattern": "^[a-z][a-z0-9_]{0,39}$"
                        },
                        "description": "Extra CSV header → lowercase token it fills, for example { \"personalizedMessage\": \"personalized_message\" }."
                      }
                    },
                    "required": [
                      "method",
                      "csvContent"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "method": {
                        "const": "sales_navigator"
                      },
                      "requestId": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$",
                        "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request."
                      },
                      "accountId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 160,
                        "description": "Optional LinkedIn sender: the public id from the partner LinkedIn accounts list or get_workspace channels.linkedin.data.senders.items. Legacy account-name IDs remain accepted. Must be connected in the selected workspace. Omit for automatic assignment; never reassigns existing leads. Sales Navigator uses an explicit selection for both fetching and sending."
                      },
                      "listUrl": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 500
                      }
                    },
                    "required": [
                      "method",
                      "listUrl"
                    ],
                    "additionalProperties": false
                  }
                ],
                "discriminator": {
                  "propertyName": "method"
                }
              },
              "example": {
                "method": "contacts",
                "requestId": "acme-add-2026-10-13-001",
                "leads": [
                  {
                    "person": "Jane Doe",
                    "company": "Acme",
                    "title": "Founder",
                    "linkedinUrl": "https://www.linkedin.com/in/example",
                    "email": "jane@acme.com",
                    "xUsername": "janedoe"
                  },
                  {
                    "person": "Sam Lee",
                    "email": "sam@acme.com"
                  },
                  {
                    "person": "Ada Ng",
                    "xUsername": "@ada_ng"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "addResult": {
                      "type": "object",
                      "properties": {
                        "method": {
                          "enum": [
                            "contacts",
                            "manual",
                            "csv",
                            "sales_navigator"
                          ]
                        },
                        "batchId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "status": {
                          "type": "string"
                        },
                        "sequenceId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "sequenceStatus": {
                          "enum": [
                            "active",
                            "paused"
                          ]
                        },
                        "reused": {
                          "type": "boolean"
                        },
                        "addedLeadIds": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "addedLeads": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "person": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "linkedinUrl": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              }
                            },
                            "required": [
                              "id",
                              "person",
                              "linkedinUrl"
                            ]
                          },
                          "description": "manual and csv only."
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "submittedCount": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "addedCount": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "duplicatesSkipped": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "invalidSkipped": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "alreadyInvitedCount": {
                              "type": "integer",
                              "minimum": 0
                            }
                          },
                          "required": [
                            "submittedCount",
                            "addedCount",
                            "duplicatesSkipped",
                            "invalidSkipped",
                            "alreadyInvitedCount"
                          ]
                        },
                        "contacted": {
                          "const": false
                        },
                        "energyCharged": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "contacts only; always 0."
                        }
                      },
                      "required": [
                        "method",
                        "sequenceId",
                        "sequenceStatus",
                        "reused",
                        "contacted"
                      ],
                      "description": "contacts, manual and csv finish in this call (status \"completed\"). sales_navigator returns the initial import status instead; poll GET /leads/imports/{batchId}."
                    },
                    "reviewUrl": {
                      "type": "string",
                      "description": "Where the customer reviews or pauses the sequence."
                    }
                  },
                  "required": [
                    "addResult",
                    "reviewUrl"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/imports/{batchId}": {
      "get": {
        "operationId": "getLeadImport",
        "tags": [
          "Leads"
        ],
        "summary": "Read a Sales Navigator import's status",
        "description": "Status of an import started by POST /sequences/{id}/leads with method sales_navigator. status is processing (still fetching), waiting (fetched; enrollment is waiting on errorCode and retries automatically), finalizing (fetched; valid people are being added), completed (queued in the sequence) or failed (stopped; read errorCode). Poll until completed or failed. Manual and CSV adds finish in their own call and return 404 here (resource import).",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "batchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "importStatus": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "{ method: \"sales_navigator\", batchId, requestId, status: processing | waiting | finalizing | completed | failed, sequence, progress: { fetchState, fetchedCount, providerTotalCount, validCandidateCount, providerLimitReached, nextAttemptAt }, summary: { addedCount, duplicatesSkipped, alreadyInvitedCount }, errorCode, createdAt, updatedAt }",
                      "properties": {
                        "status": {
                          "enum": [
                            "processing",
                            "waiting",
                            "finalizing",
                            "completed",
                            "failed"
                          ]
                        }
                      }
                    }
                  },
                  "required": [
                    "importStatus"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads": {
      "get": {
        "operationId": "listLeads",
        "tags": [
          "Leads"
        ],
        "summary": "List leads across channels",
        "description": "The same view as the Leads screen: who is engaged, who booked, who went quiet. engaged=1 or sinceDays>0 limits to people with recent activity; booked=1 to booked meetings; q searches person and company. Bounded by limit (max 500). To recover a lost removal ID, search with q and no activity/stage filters, identify the correct person and sequence, and read that lead's removal.id. Pass it to POST /leads/undo-remove. removal is null when no current Undo event is available; do not re-add the person as a workaround.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "stage",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Lead stage, e.g. queued, invited, connected, messaged, replied, meeting_booked."
          },
          {
            "name": "engaged",
            "in": "query",
            "schema": {
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "sinceDays",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "booked",
            "in": "query",
            "schema": {
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "returned": {
                      "type": "integer"
                    },
                    "leads": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "person": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "removal": {
                            "anyOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "removedAt": {
                                    "type": "string",
                                    "format": "date-time"
                                  },
                                  "undoAfter": {
                                    "type": "string",
                                    "format": "date-time"
                                  }
                                },
                                "required": [
                                  "id",
                                  "removedAt",
                                  "undoAfter"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Current removal metadata, or null when no current Undo event is available. Recover id here if the original remove response was not saved. A non-null value does not bypass the safety checks performed by POST /leads/undo-remove."
                          }
                        },
                        "required": [
                          "id",
                          "removal"
                        ]
                      }
                    }
                  },
                  "required": [
                    "count",
                    "returned",
                    "leads"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/{id}/thread": {
      "get": {
        "operationId": "getLeadThread",
        "tags": [
          "Leads"
        ],
        "summary": "Read a lead's LinkedIn conversation",
        "description": "Read incoming and outgoing messages through the lead's saved sender, including paused sequences and removed leads whose history is retained. LinkedIn only. Each page is oldest first; the first page contains the newest messages and nextCursor reads the next older page, which should be prepended. Continue until nextCursor is null. Cursors are opaque, expire after 30 minutes, and work only for the same workspace, lead and connected sender. Start again without a cursor after reconnecting. available=false and an empty messages array mean no LinkedIn thread has been recorded yet, not a verified absence of conversation on LinkedIn. Text and attachment presence only; no attachment downloads. Sends nothing, does not decide drafts or mark messages read. 400 invalid_cursor for invalid, mismatched or expired cursors; 409 thread_account_unavailable when the original sender must be reconnected; 429 rate_limited includes Retry-After; 502 thread_unavailable on provider failure, never a successful empty thread.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "schema": {
              "const": "linkedin",
              "default": "linkedin"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 12000
            },
            "description": "Use thread.nextCursor from the previous page; omit for the newest messages."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "thread": {
                      "type": "object",
                      "properties": {
                        "leadId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "channel": {
                          "const": "linkedin"
                        },
                        "available": {
                          "type": "boolean"
                        },
                        "messages": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "direction": {
                                "enum": [
                                  "inbound",
                                  "outbound"
                                ]
                              },
                              "text": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "timestamp": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "hasAttachments": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "id",
                              "direction",
                              "text",
                              "timestamp",
                              "hasAttachments"
                            ]
                          }
                        },
                        "nextCursor": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "hasMore": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "leadId",
                        "channel",
                        "available",
                        "messages",
                        "nextCursor",
                        "hasMore"
                      ]
                    }
                  },
                  "required": [
                    "thread"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "thread_unavailable: conversation could not be read; check the connection and retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/{id}": {
      "get": {
        "operationId": "getLead",
        "tags": [
          "Leads"
        ],
        "summary": "Read one lead",
        "description": "One lead in the same shape as GET /leads: identity, account, sequence, stage, milestones, reply sentiment, last error and removal metadata. If the original removal response was not saved, use lead.removal.id with POST /leads/undo-remove. removal is null when no current Undo event is available. 404 not_found (resource lead) outside this workspace.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lead": {
                      "type": "object",
                      "additionalProperties": true,
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "person": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "removal": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "format": "uuid"
                                },
                                "removedAt": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "undoAfter": {
                                  "type": "string",
                                  "format": "date-time"
                                }
                              },
                              "required": [
                                "id",
                                "removedAt",
                                "undoAfter"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Current removal metadata, or null when no current Undo event is available. Recover id here if the original remove response was not saved. A non-null value does not bypass the safety checks performed by POST /leads/undo-remove."
                        }
                      },
                      "required": [
                        "id",
                        "removal"
                      ]
                    }
                  },
                  "required": [
                    "lead"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "hardDeleteLead",
        "tags": [
          "Leads"
        ],
        "summary": "Permanently delete an unused removed lead",
        "description": "REST-only. Irreversibly deletes one already-removed lead with no outreach or processing history, replies, opt-outs, meetings, protected linked records, other matching workspace records or company exclusions. No dashboard action or MCP tool. Send no body or query parameters; no force override is supported. The current removal must remain valid and its settling period must have ended: follow removal.undoAfter or the 409 Retry-After header (up to ten minutes after removal). The source import must be finished or cancelled. Use a paused sequence for import tests. After confirmed deletion, add the profile again with a new requestId; old import receipts and requestIds remain unchanged and old review candidates are not reopened. Deletion removes this record's duplicate protection, so future approved imports or Plays can add the person again. Normal duplicate, pending-invitation, exclusion and sending rules still apply. Deletion never withdraws LinkedIn invitations or messages. GET on a deleted ID returns 404; retrying DELETE with that old ID also returns 404 and cannot delete a new enrollment. 409 lead_delete_blocked returns reason and message, optionally retryAfterSeconds. 503 lead_delete_unavailable means deletion could not be confirmed: read the lead or retry DELETE with the same ID. No-store.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deletion": {
                      "type": "object",
                      "properties": {
                        "leadId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "const": "deleted"
                        }
                      },
                      "required": [
                        "leadId",
                        "status"
                      ]
                    }
                  },
                  "required": [
                    "deletion"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_request: invalid lead ID, body or query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (resource lead): absent, foreign or already deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "lead_delete_blocked with reason removal_required, state_changed, work_in_progress, outreach_started, contact_stopped, related_history, company_excluded or person_conflict; nothing deleted. A settling delay also returns Retry-After and retryAfterSeconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "lead_delete_unavailable: deletion could not be confirmed; retry the same lead ID or read it",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/{id}/input": {
      "post": {
        "operationId": "setLeadInput",
        "tags": [
          "Leads"
        ],
        "summary": "Supply per-person values for a held message step",
        "description": "Store the customer's values for a LinkedIn message, email, X DM or Instagram DM step declared with tool { kind: \"customer_input\", tokens }, for example a link to a video they recorded. Each value is written to every not-yet-sent step of the lead's sequence that declares it. 1-5 entries; keys are the sequence's token names; a *_url key must be an http(s) URL. A step that sends each person their own file (customer_input attachment) takes files: { [key]: uploadTicket } after the bytes were uploaded through POST /leads/{id}/input/upload. Nothing is sent in this call: the paced engine sends on its next run. 409 with nothing changed: lead_input_already_replied, lead_input_sequence_finished, lead_input_step_already_sent, lead_input_channel_unavailable, lead_input_no_sequence, lead_input_sequence_has_no_input_step, lead_input_unknown_key, lead_input_invalid_value, lead_input_step_uses_generated_asset, lead_input_not_a_file, lead_input_not_text, lead_input_file_invalid, lead_input_file_unavailable, lead_input_file_does_not_fit, lead_input_email_file_not_allowed, lead_input_file_wrong_type, lead_input_file_too_large, lead_input_upload_expired, lead_input_upload_invalid, lead_input_upload_missing.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "values": {
                    "type": "object",
                    "propertyNames": {
                      "pattern": "^[a-z][a-z0-9_]{0,39}$"
                    },
                    "additionalProperties": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 2000
                    },
                    "minProperties": 1,
                    "maxProperties": 5
                  },
                  "files": {
                    "type": "object",
                    "propertyNames": {
                      "pattern": "^[a-z][a-z0-9_]{0,39}$"
                    },
                    "additionalProperties": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 2000
                    },
                    "minProperties": 1,
                    "maxProperties": 1,
                    "description": "The file slot's key mapped to the uploadTicket from POST /leads/{id}/input/upload."
                  }
                },
                "required": [
                  "values",
                  "files"
                ],
                "additionalProperties": false
              },
              "example": {
                "values": {
                  "video_url": "https://example.com/videos/jane"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stored": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "{ leadId, person, company, linkedinUrl, sequenceId, sequenceName, stepIndex, storedKeys, storedFiles?, complete, stillMissing, willSendOn, stillWaitingInSequence }"
                    }
                  },
                  "required": [
                    "stored"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/{id}/input/upload": {
      "post": {
        "operationId": "requestLeadFileUpload",
        "tags": [
          "Leads"
        ],
        "summary": "Get a one-time upload link for one person's file",
        "description": "For a LinkedIn message, email, X DM or Instagram DM step that sends each person their own file (customer_input attachment), returns { uploadUrl, method: \"PUT\", headers, uploadTicket, expiresAt, maxBytes, appUrl }. PUT the file's bytes to uploadUrl with Content-Type: application/octet-stream before expiresAt (two hours), then POST /leads/{id}/input with files: { [key]: uploadTicket }. Limits are each provider's, checked before any upload: a LinkedIn message carries at most 5 files and 15 MB together with the step's own attachments; an email step takes one document, image or MP4 up to 18 MB (1.5 MB when sent from a Microsoft mailbox, checked at send time); an X DM step takes one image up to 5 MB, GIF up to 15 MB or MP4 video up to 50 MB and 140 seconds. Nothing is compressed: a larger file is refused with 409 lead_input_file_too_large and a message naming the limit, the file's size and the way forward (compress it, or use a video link); a wrong type is lead_input_file_wrong_type or lead_input_email_file_not_allowed. Stores nothing and sends nothing. 409 with nothing changed: lead_input_not_a_file, lead_input_file_invalid, lead_input_unknown_key, lead_input_step_already_sent and the other lead_input_* states above.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string",
                    "pattern": "^[a-z][a-z0-9_]{0,39}$"
                  },
                  "fileName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "size": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50000000
                  }
                },
                "required": [
                  "key",
                  "fileName",
                  "size"
                ],
                "additionalProperties": false
              },
              "example": {
                "key": "personal_file",
                "fileName": "jane-doe.mp4",
                "size": 12400000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "upload": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "{ leadId, person, sequenceId, sequenceName, key, uploadUrl, method, headers, uploadTicket, expiresAt, maxBytes, appUrl }"
                    }
                  },
                  "required": [
                    "upload"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/move/preview": {
      "post": {
        "operationId": "previewLeadMove",
        "tags": [
          "Leads"
        ],
        "summary": "Preview moving untouched people",
        "description": "Read-only eligibility across LinkedIn, email and X for up to 500 leads and a non-archived destination in this workspace. Queued on one channel is not sufficient. Returns eligible and excluded people with reasons. Does not pause, approve, move or send.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leadIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "minItems": 1,
                    "maxItems": 500
                  },
                  "sequenceId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "leadIds",
                  "sequenceId"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sequenceId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "eligibleCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "blockedCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "leadId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "person": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "sourceSequenceId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "eligible": {
                            "type": "boolean"
                          },
                          "reason": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "message": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "leadId",
                          "person",
                          "sourceSequenceId",
                          "eligible",
                          "reason",
                          "message"
                        ]
                      }
                    }
                  },
                  "required": [
                    "sequenceId",
                    "eligibleCount",
                    "blockedCount",
                    "results"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/move": {
      "post": {
        "operationId": "moveLeads",
        "tags": [
          "Leads"
        ],
        "summary": "Schedule a lead move after five seconds",
        "description": "Schedules the exact selection to move after a five-second server delay; execution checks eligibility again. Reuse the identical operationId, leadIds and sequenceId on retries. Save operationId for polling or cancellation. Moved people follow the destination's normal schedule while existing personal pauses, sender bindings, lead IDs, history and Play attribution stay intact. Does not approve messages or activate a sequence. Inspect per-person blocked reasons when completed. 409 idempotency_conflict means the operation ID belongs to a different request; 503 sequence_move_unconfirmed requires reading or retrying the same operation, never a replacement.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leadIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "minItems": 1,
                    "maxItems": 500
                  },
                  "sequenceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "operationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required stable UUID for this exact selection and destination. Reuse for retries; a different payload with the same ID conflicts."
                  }
                },
                "required": [
                  "leadIds",
                  "sequenceId",
                  "operationId"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "operationId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "sequenceId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "requestLeadIds": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "minItems": 1,
                      "maxItems": 500
                    },
                    "status": {
                      "enum": [
                        "pending",
                        "running",
                        "completed",
                        "cancelled",
                        "failed"
                      ],
                      "description": "A failed operation may contain confirmed partial results. Compare requestLeadIds with results: missing people need review; never assume they were blocked or remained unmoved."
                    },
                    "executeAfter": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "serverNow": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "movedCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "blockedCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "leadId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "person": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "sourceSequenceId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "enum": [
                              "moved",
                              "blocked"
                            ]
                          },
                          "reason": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "message": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "leadId",
                          "person",
                          "sourceSequenceId",
                          "status",
                          "reason",
                          "message"
                        ]
                      }
                    }
                  },
                  "required": [
                    "operationId",
                    "sequenceId",
                    "requestLeadIds",
                    "status",
                    "executeAfter",
                    "serverNow",
                    "movedCount",
                    "blockedCount",
                    "results"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "getLeadMove",
        "tags": [
          "Leads"
        ],
        "summary": "Read a saved move operation",
        "description": "Read-only lifecycle status in the current workspace: pending, running, completed, cancelled or failed. Polling never executes or restarts a move. Keep the operationId returned by the original POST for recovery. 404 not_found for an unavailable operation.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "operationId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "operationId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "sequenceId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "requestLeadIds": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "minItems": 1,
                      "maxItems": 500
                    },
                    "status": {
                      "enum": [
                        "pending",
                        "running",
                        "completed",
                        "cancelled",
                        "failed"
                      ],
                      "description": "A failed operation may contain confirmed partial results. Compare requestLeadIds with results: missing people need review; never assume they were blocked or remained unmoved."
                    },
                    "executeAfter": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "serverNow": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "movedCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "blockedCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "leadId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "person": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "sourceSequenceId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "enum": [
                              "moved",
                              "blocked"
                            ]
                          },
                          "reason": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "message": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "leadId",
                          "person",
                          "sourceSequenceId",
                          "status",
                          "reason",
                          "message"
                        ]
                      }
                    }
                  },
                  "required": [
                    "operationId",
                    "sequenceId",
                    "requestLeadIds",
                    "status",
                    "executeAfter",
                    "serverNow",
                    "movedCount",
                    "blockedCount",
                    "results"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/move/cancel": {
      "post": {
        "operationId": "cancelLeadMove",
        "tags": [
          "Leads"
        ],
        "summary": "Cancel a pending move",
        "description": "Cancels the exact operationId only during its five-second window and before execution claims it. This is Undo during the five-second delay, not a reversal after completion. The cancel and execution claims compete atomically; inspect the returned status. cancelled confirms no people moved; running or completed means cancellation was too late. A pending response with serverNow at or after executeAfter also means the cancellation window closed. Repeating cancellation is safe. Does not rewind progress, alter sequence approval or send.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "operationId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "operationId"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "operationId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "sequenceId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "requestLeadIds": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "minItems": 1,
                      "maxItems": 500
                    },
                    "status": {
                      "enum": [
                        "pending",
                        "running",
                        "completed",
                        "cancelled",
                        "failed"
                      ],
                      "description": "A failed operation may contain confirmed partial results. Compare requestLeadIds with results: missing people need review; never assume they were blocked or remained unmoved."
                    },
                    "executeAfter": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "serverNow": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "movedCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "blockedCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "leadId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "person": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "sourceSequenceId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "enum": [
                              "moved",
                              "blocked"
                            ]
                          },
                          "reason": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "message": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "leadId",
                          "person",
                          "sourceSequenceId",
                          "status",
                          "reason",
                          "message"
                        ]
                      }
                    }
                  },
                  "required": [
                    "operationId",
                    "sequenceId",
                    "requestLeadIds",
                    "status",
                    "executeAfter",
                    "serverNow",
                    "movedCount",
                    "blockedCount",
                    "results"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/undo-remove": {
      "post": {
        "operationId": "undoLeadRemoval",
        "tags": [
          "Leads"
        ],
        "summary": "Undo specific lead removals",
        "description": "Explicitly restores the same leads to their original sequences and progress. Pass removal IDs from the remove response or the lead's removal.id. Paused sequences stay paused. Retrying the same IDs is harmless and cannot undo a newer removal. Each result is restored, already_restored or blocked with a reason and message; check all results, including on HTTP 200. Nothing is sent in this request. Company exclusions and cancelled imports are not undone. Historical removals are eligible only when untouched pooled enrollment can be proven; no past state is guessed.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "removalIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "minItems": 1,
                    "maxItems": 500
                  }
                },
                "required": [
                  "removalIds"
                ],
                "additionalProperties": false
              },
              "example": {
                "removalIds": [
                  "00000000-0000-4000-8000-000000000004"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "restoration": {
                      "type": "object",
                      "properties": {
                        "restoredCount": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "alreadyRestoredCount": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "blockedCount": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "removalId": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "leadId": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "status": {
                                "enum": [
                                  "restored",
                                  "already_restored",
                                  "blocked"
                                ]
                              },
                              "reason": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "message": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "removalId",
                              "leadId",
                              "status",
                              "reason",
                              "message"
                            ]
                          }
                        }
                      },
                      "required": [
                        "restoredCount",
                        "alreadyRestoredCount",
                        "blockedCount",
                        "results"
                      ]
                    }
                  },
                  "required": [
                    "restoration"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/remove": {
      "post": {
        "operationId": "removeLeads",
        "tags": [
          "Leads"
        ],
        "summary": "Remove leads, cancel an import or block companies",
        "description": "Stops outreach and returns removals [{ leadId, removalId, undoAfter }]. Use POST /leads/undo-remove with those exact removal IDs to reverse removal. Removed leads stay out of Play review and ordinary imports. Uncontacted leads leave the queue; contacted leads keep their stage and milestones and get no further automated steps. Sent invitations and messages are never reversed. target companies also puts those employers on the do-not-contact list. 404 not_found (resource import) when batchId is not one of this workspace's imports.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "target": {
                        "const": "leads"
                      },
                      "leadIds": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "minItems": 1,
                        "maxItems": 500
                      }
                    },
                    "required": [
                      "target",
                      "leadIds"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "target": {
                        "const": "import"
                      },
                      "batchId": {
                        "type": "string",
                        "format": "uuid"
                      }
                    },
                    "required": [
                      "target",
                      "batchId"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "target": {
                        "const": "companies"
                      },
                      "companies": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 240
                        },
                        "minItems": 1,
                        "maxItems": 100,
                        "description": "Employers to put on the workspace do-not-contact list; everyone queued there is stopped and Plays stop finding people there."
                      }
                    },
                    "required": [
                      "target",
                      "companies"
                    ],
                    "additionalProperties": false
                  }
                ],
                "discriminator": {
                  "propertyName": "target"
                }
              },
              "example": {
                "target": "leads",
                "leadIds": [
                  "00000000-0000-4000-8000-000000000003"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removal": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "{ ok: true, selectedCount, removedBeforeContact, automationStoppedAfterContact, alreadyStopped, notFoundCount, importCancelled, excludedCompanies?, removals: [{ leadId, removalId, undoAfter }], historyPreserved: true, sentActionsReversed: false, summary }"
                    }
                  },
                  "required": [
                    "removal"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/people/searches": {
      "post": {
        "operationId": "createPeopleSearch",
        "tags": [
          "People search"
        ],
        "summary": "Create or revise a people-search Play and optionally run it",
        "description": "Find people from a targeting, the same way the PumpGTM agent does. Provide targeting (creates a Play, or revises playId at expectedRevision, the play.revision from the previous response), a playId alone (use the Play as is), or both. run: false (default) prepares and returns 200 with the targeting summary; run: true searches and returns 201 with the review batch and candidates. requestId is required when run is true: a run is billed, so a retry must carry the same requestId to replay the stored result (reused: true) instead of searching and charging again. sequenceId sets the Play's sequence for future leads only; it does not move existing people, approve messages or start a draft. A run crawls toward candidateCount, up to 100 people; each person found costs 2 Energy on metered workspaces (drawn from the partner pool for partner users) or, for partners without Energy, counts toward partner lead metering (50 free, then 403 billing_required with a checkout link in message). Finding people never contacts anyone. 409 targeting_needs_clarification with ambiguities when targeting is incomplete; company-name ambiguity never blocks (read companyResolution). 409 draft_changed when the Play changed since expectedRevision. 403 user_lead_cap_reached or billing_required for a partner user who may not search.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "targeting": {
                    "type": "object",
                    "properties": {
                      "schemaVersion": {
                        "const": 1
                      },
                      "name": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 120,
                        "description": "A short customer-facing name for this search."
                      },
                      "candidateCount": {
                        "type": "integer",
                        "minimum": 5,
                        "maximum": 100,
                        "description": "The exact number of candidates to return."
                      },
                      "hardFilters": {
                        "type": "object",
                        "properties": {
                          "currentTitleIncludesAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 120
                            },
                            "minItems": 1,
                            "maxItems": 40,
                            "description": "Alternative literal phrases; a person's current title must contain at least one."
                          },
                          "currentFunctionsAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "Engineering",
                                "Sales",
                                "Consulting",
                                "Marketing",
                                "Operations",
                                "Finance",
                                "Research",
                                "Customer Success and Support",
                                "Arts and Design",
                                "Human Resources",
                                "Legal",
                                "Product Management"
                              ]
                            },
                            "maxItems": 40,
                            "description": "Alternative current job functions. Use only when non-negotiable. One of the listed values only."
                          },
                          "currentSenioritiesAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "Owner / Partner",
                                "CXO",
                                "Vice President",
                                "Director",
                                "Experienced Manager",
                                "Entry Level Manager",
                                "Strategic",
                                "Senior",
                                "Entry Level",
                                "In Training"
                              ]
                            },
                            "maxItems": 40,
                            "description": "Alternative current seniority levels. Use only when non-negotiable. One of the listed values only; put finer wording such as Head of or SVP in semanticQuery."
                          },
                          "personCountriesAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 240
                            },
                            "maxItems": 40,
                            "description": "Alternative countries where the person must be located."
                          },
                          "currentCompanyNamesAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 240
                            },
                            "maxItems": 40,
                            "description": "Alternative exact current-employer names, only for a named account list."
                          },
                          "currentCompanyDomainsAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 240
                            },
                            "maxItems": 40,
                            "description": "Alternative exact current-employer website domains; a domain pins one company exactly."
                          },
                          "currentCompanyLinkedInUrlsAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 240
                            },
                            "maxItems": 40,
                            "description": "Alternative current-employer LinkedIn company URLs."
                          },
                          "currentCompanyIndustriesAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 240
                            },
                            "maxItems": 40,
                            "description": "Alternative canonical company industries."
                          },
                          "currentCompanyTypesAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 240
                            },
                            "maxItems": 40,
                            "description": "Alternative canonical company ownership types."
                          },
                          "currentCompanyHeadcount": {
                            "type": "object",
                            "properties": {
                              "minimum": {
                                "type": "integer",
                                "minimum": 1,
                                "maximum": 10000000
                              },
                              "maximum": {
                                "type": "integer",
                                "minimum": 1,
                                "maximum": 10000000
                              }
                            },
                            "required": [],
                            "additionalProperties": false
                          },
                          "currentCompanyInvestorsAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 240
                            },
                            "maxItems": 40,
                            "description": "Alternative canonical investors or accelerators backing the current company (Y Combinator, not YC)."
                          },
                          "currentCompanyHiringRolesAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 240
                            },
                            "maxItems": 40,
                            "description": "Alternative role phrases the current company must have an open job posting for right now."
                          },
                          "currentCompanyHiringPostedWithinDays": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 365,
                            "description": "Defaults to 30 when hiring roles are given."
                          },
                          "excludedCurrentFunctionsAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "Engineering",
                                "Sales",
                                "Consulting",
                                "Marketing",
                                "Operations",
                                "Finance",
                                "Research",
                                "Customer Success and Support",
                                "Arts and Design",
                                "Human Resources",
                                "Legal",
                                "Product Management"
                              ]
                            },
                            "maxItems": 40,
                            "description": "Current job functions that must be excluded. One of the listed values only."
                          },
                          "excludedCurrentSenioritiesAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "Owner / Partner",
                                "CXO",
                                "Vice President",
                                "Director",
                                "Experienced Manager",
                                "Entry Level Manager",
                                "Strategic",
                                "Senior",
                                "Entry Level",
                                "In Training"
                              ]
                            },
                            "maxItems": 40,
                            "description": "Current seniority levels that must be excluded. One of the listed values only; put finer wording such as Head of or SVP in semanticQuery."
                          },
                          "excludedCurrentCompanyNamesAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 240
                            },
                            "maxItems": 40,
                            "description": "Exact current-employer names that must be excluded."
                          },
                          "excludedCurrentCompanyTypesAny": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 240
                            },
                            "maxItems": 40,
                            "description": "Company ownership types that must be excluded."
                          }
                        },
                        "required": [
                          "currentTitleIncludesAny"
                        ],
                        "additionalProperties": false
                      },
                      "semanticQuery": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 2000,
                        "description": "Plain-language description of product, workload, responsibility and business-model fit. Descriptive requirements go here, not in hard filters."
                      },
                      "defaultSequenceId": {
                        "anyOf": [
                          {
                            "type": "string",
                            "format": "uuid"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "required": [
                      "name",
                      "candidateCount",
                      "hardFilters"
                    ],
                    "additionalProperties": false
                  },
                  "playId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "expectedRevision": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan."
                  },
                  "sequenceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "run": {
                    "type": "boolean",
                    "default": false
                  },
                  "requestId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$",
                    "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request."
                  }
                },
                "required": [],
                "additionalProperties": false,
                "anyOf": [
                  {
                    "required": [
                      "targeting"
                    ]
                  },
                  {
                    "required": [
                      "playId"
                    ]
                  }
                ],
                "if": {
                  "properties": {
                    "run": {
                      "const": true
                    }
                  },
                  "required": [
                    "run"
                  ]
                },
                "then": {
                  "required": [
                    "requestId"
                  ]
                }
              },
              "example": {
                "run": true,
                "requestId": "people-search-2026-10-06-001",
                "targeting": {
                  "name": "Heads of sales at mid-market SaaS",
                  "candidateCount": 20,
                  "hardFilters": {
                    "currentTitleIncludesAny": [
                      "Head of Sales",
                      "VP Sales"
                    ]
                  },
                  "semanticQuery": "B2B SaaS selling to mid-market"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "Prepared (200): { play: { id, revision }, plan, ambiguities: [], companyResolution, readyToRun, reviewUrl?, searched: false, contacted: false }. Run (201): { play: { id, revision }, batch: { id, status: draft | sample_ready | approved | imported | rejected, ... }, candidates: [{ id, person, title, company, linkedinUrl, decision: undecided | approved | rejected, ... }], reviewUrl?, searched: true, contacted: false }."
                }
              }
            }
          },
          "201": {
            "description": "Search ran: review batch and candidates returned; nobody was contacted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "Prepared (200): { play: { id, revision }, plan, ambiguities: [], companyResolution, readyToRun, reviewUrl?, searched: false, contacted: false }. Run (201): { play: { id, revision }, batch: { id, status: draft | sample_ready | approved | imported | rejected, ... }, candidates: [{ id, person, title, company, linkedinUrl, decision: undecided | approved | rejected, ... }], reviewUrl?, searched: true, contacted: false }."
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "energy_exhausted: this metered workspace has no Energy left for the action; nothing changed. Follow topUpUrl.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/people/searches/{playId}/run": {
      "post": {
        "operationId": "runPeopleSearch",
        "tags": [
          "People search"
        ],
        "summary": "Run an existing people-search Play",
        "description": "Runs a saved people-search Play as is; same metering and result as createPeopleSearch with run: true. requestId is required: a run is billed, so a retry must carry the same requestId to replay the stored result instead of searching and charging again. 404 not_found (resource play) when the Play does not exist or is not a people-search Play.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "playId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requestId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$",
                    "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request."
                  },
                  "sequenceId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "requestId"
                ],
                "additionalProperties": false
              },
              "example": {
                "requestId": "people-search-rerun-2026-10-06-001"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "energy_exhausted: this metered workspace has no Energy left for the action; nothing changed. Follow topUpUrl.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/people/reviews/{batchId}": {
      "get": {
        "operationId": "getPeopleReview",
        "tags": [
          "People search"
        ],
        "summary": "Read a review batch and its candidates",
        "description": "One review batch: batch counts, the targeting summary and each candidate with its current decision (undecided, approved or rejected). batch.status is draft (being prepared), sample_ready (ready to review), approved, imported (finished; good fits queued) or rejected. 404 not_found (resource review).",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "batchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "{ batch: { id, status: draft | sample_ready | approved | imported | rejected, planId, planRevision, proposedCount, approvedCount, importedCount, ... }, target, candidates: [{ id, person, title, company, linkedinUrl, location, matchReason, evidence, linkedinVerified, recentActivityAt, decision: undecided | approved | rejected, sequenceId }] }"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/people/reviews/{batchId}/decisions": {
      "post": {
        "operationId": "decidePeopleReview",
        "tags": [
          "People search"
        ],
        "summary": "Record good-fit decisions and enroll",
        "description": "Record the customer's good-fit decisions on a review batch. 1-100 decisions per call; good_fit approves, not_a_fit rejects. Partial decisions persist. finish: true requires every candidate decided and queues the good fits into their sequence (the call's sequenceId, a per-decision override, or the Play's default); summary, addedLeadIds, addedLeads and sequences are present only on that finishing call, and reviewUrl is then present. Nothing is sent in this call. 409 all_candidates_require_a_decision when finishing with undecided people.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "batchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "decisions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "candidateId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "decision": {
                          "enum": [
                            "good_fit",
                            "not_a_fit"
                          ]
                        },
                        "sequenceId": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Optional per-person override of the sequence this good fit goes into."
                        },
                        "feedbackReason": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 120
                        },
                        "feedbackNote": {
                          "type": "string",
                          "maxLength": 1000
                        }
                      },
                      "required": [
                        "candidateId",
                        "decision"
                      ],
                      "additionalProperties": false
                    },
                    "minItems": 1,
                    "maxItems": 100
                  },
                  "sequenceId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Applies to every good fit in this call."
                  },
                  "finish": {
                    "type": "boolean",
                    "default": false
                  },
                  "requestId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$",
                    "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request."
                  }
                },
                "required": [
                  "decisions"
                ],
                "additionalProperties": false
              },
              "example": {
                "sequenceId": "00000000-0000-4000-8000-000000000001",
                "finish": true,
                "decisions": [
                  {
                    "candidateId": "00000000-0000-4000-8000-000000000004",
                    "decision": "good_fit"
                  },
                  {
                    "candidateId": "00000000-0000-4000-8000-000000000005",
                    "decision": "not_a_fit",
                    "feedbackReason": "wrong seniority"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "{ batch, candidates: [{ ..., decision: undecided | approved | rejected }], reviewUrl?, contacted: false } plus, only when finish is true: summary: { approvedCount, rejectedCount, addedCount, duplicatesSkipped, alreadyInvitedCount }, addedLeadIds, addedLeads, sequences"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/progress": {
      "get": {
        "operationId": "getProgress",
        "tags": [
          "Results"
        ],
        "summary": "Read LinkedIn pace and outcomes",
        "description": "Current LinkedIn sending pace and outcome counts over the last sinceDays days (default 7): invites, acceptances, messages, replies and meetings per account. Saved observations, not a live provider probe.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "sinceDays",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0,
              "default": 7
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/reports/funnel": {
      "get": {
        "operationId": "getFunnelReport",
        "tags": [
          "Results"
        ],
        "summary": "Read the lead funnel by sequence or account",
        "description": "Funnel outcomes grouped by sequence (default) or by connected account, plus split-test arms, so a backend can report or decide without scraping a screen. excludedWarmupAccounts is a compatibility field and is always empty.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "group_by",
            "in": "query",
            "schema": {
              "enum": [
                "sequence",
                "account"
              ],
              "default": "sequence"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "groupBy": {
                      "type": "string"
                    },
                    "excludedWarmupAccounts": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "total": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "groups": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "funnel": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "funnel"
                        ]
                      }
                    },
                    "experimentArms": {
                      "type": [
                        "array",
                        "object"
                      ]
                    }
                  },
                  "required": [
                    "groupBy",
                    "excludedWarmupAccounts",
                    "total",
                    "groups",
                    "experimentArms"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/replies": {
      "get": {
        "operationId": "listReplies",
        "tags": [
          "Replies"
        ],
        "summary": "Read pending replies",
        "description": "Includes LinkedIn, email and X replies, only while they wait on you as the Inbox's Needs you shows them: a reply answered or cleared from your side, snoozed, booked or opted out since leaves the list until the person writes again. Some X conversations have no draft; enabled scheduling partners obtain their replyVersion through GET /leads/{id}/reply-decisions. Encrypted text can be unavailable. This is a bounded pending queue, not a complete conversation archive.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "replies": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "replies"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/replies/{id}/decide": {
      "post": {
        "operationId": "decideReply",
        "tags": [
          "Replies"
        ],
        "summary": "Decide a pending reply",
        "description": "Optional sendAt schedules a text-only send for enabled agency partners (LinkedIn, email or X), returning 202 { ok, scheduledReply }. Requires Idempotency-Key and a future RFC 3339 instant within 30 days. Null/invalid sendAt or other decisions with sendAt are refused, never sent immediately. Poll /scheduled-replies/{id}. Without sendAt, runs exactly the same code as the inbox buttons. send posts the draft (text overrides it); invite, booking_link and start_sequence act on the thread; snooze waits days; meeting_booked, dismiss and opt_out close it. by is recorded for the audit trail. 404 when the reply is not pending in this workspace; 409 with the result when the decision could not be applied.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[!-~]+$"
            },
            "description": "Required when sendAt is present."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sendAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Future RFC 3339 instant with Z or numeric offset, at most 30 days ahead. Earliest send time; the worker runs every minute."
                  },
                  "decision": {
                    "enum": [
                      "send",
                      "invite",
                      "booking_link",
                      "snooze",
                      "start_sequence",
                      "meeting_booked",
                      "dismiss",
                      "opt_out"
                    ]
                  },
                  "text": {
                    "type": "string",
                    "description": "send only: replaces the generated draft."
                  },
                  "days": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "snooze only."
                  },
                  "by": {
                    "type": "string",
                    "description": "Who decided; defaults to api."
                  }
                },
                "required": [
                  "decision"
                ]
              },
              "example": {
                "decision": "snooze",
                "days": 14,
                "by": "crm-bot"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "ok"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "202": {
            "description": "Reply scheduled; poll scheduledReply.id for delivery status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "ok"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/activity": {
      "get": {
        "operationId": "listActivity",
        "tags": [
          "Results"
        ],
        "summary": "Read the activity ledger",
        "description": "Use action=x_dm and outcome=ok to inspect confirmed X sends. Other actions may be skipped/failed. Bounded recent ledger; polling supplements best-effort webhook delivery.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "action",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated action names, e.g. x_dm,x_follow"
          },
          {
            "name": "outcome",
            "in": "query",
            "schema": {
              "enum": [
                "ok",
                "failed",
                "skipped"
              ]
            }
          },
          {
            "name": "sinceDays",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "operationId": "listWebhooks",
        "tags": [
          "Webhooks"
        ],
        "summary": "List enabled subscriptions",
        "description": "Lists workspace webhook URLs and events; never returns signing secrets.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhooks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "url": {
                            "type": "string"
                          },
                          "events": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "createdAt": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "url",
                          "events",
                          "createdAt"
                        ]
                      }
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "webhooks",
                    "events"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createWebhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Subscribe to signed events",
        "description": "Maximum 10 enabled hooks. Save the returned secret securely; it is shown only at creation. HTTPS port 443 and publicly resolving IPv4 DNS required. Private/mixed IPs, URL credentials, fragments and redirects are rejected. Registration is not idempotent: list before retrying after a timeout; 409 webhook_limit_reached at the maximum. Delivery is best-effort: up to three attempts, retried on network errors, 5xx and 429; not a durable replay queue. Verify signatures on the exact raw body (X-PumpGTM-Signature, t=<unix>,v1=<hex HMAC-SHA256 of t + \".\" + body>; reject t older than 5 minutes) and deduplicate event IDs. x.followed means an inbound follow of your connected account. lead.messaged includes successful x_dm with channel x; reply.received can include unreadable encrypted content. linkedin.connected fires on the partner workspace when an end user completes a hosted connect link; register it with the partner key. linkedin.disconnected fires when a connected LinkedIn identity stops being usable (source: provider, dashboard or api), on the owning workspace and, for a partner end user, on the partner workspace. linkedin.limited fires once when LinkedIn declines an account's connection requests and invites are held (data.account{id,displayName}, reason invite_limit, heldSince, retryAt = earliest automatic retry, attempt 1..3; a failed retry fires it again with the next attempt); linkedin.resumed fires when a retry goes through (data.account, resumedAt, warmupRestarted false: the account keeps its existing warm-up progress or full pace). Messages and other steps keep running during a hold; nothing to do on your side.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2000
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "enum": [
                        "reply.received",
                        "lead.invited",
                        "lead.accepted",
                        "lead.messaged",
                        "lead.emailed",
                        "lead.meeting_booked",
                        "x.followed",
                        "linkedin.connected",
                        "linkedin.disconnected",
                        "linkedin.limited",
                        "linkedin.resumed",
                        "linkedin.watched_post",
                        "x.competitor_follower",
                        "x.intent_detected",
                        "ping"
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 15
                  }
                },
                "required": [
                  "url",
                  "events"
                ]
              },
              "example": {
                "url": "https://hooks.example.com/pump",
                "events": [
                  "reply.received",
                  "lead.messaged",
                  "x.followed"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "url": {
                      "type": "string"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "secret": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "url",
                    "events",
                    "secret"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhooks/{id}/test": {
      "post": {
        "operationId": "testWebhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Schedule a signed ping",
        "description": "202 means the ping was scheduled, not that the receiver accepted it. Verify the event at your receiver.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "event": {
                      "const": "ping"
                    }
                  },
                  "required": [
                    "ok",
                    "id",
                    "event"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhooks/{id}": {
      "delete": {
        "operationId": "deleteWebhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Disable a subscription",
        "description": "Only an enabled hook belonging to the selected workspace can be disabled. A subsequent delete returns 404. Already queued delivery may still complete.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "ok",
                    "id"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/scheduled-replies": {
      "get": {
        "operationId": "listScheduledReplies",
        "tags": [
          "Replies"
        ],
        "summary": "List scheduled replies",
        "description": "API-only private partner capability. Requires an enabled partner workspace/Team-owner key and optionally X-PumpGTM-User for its active child workspace. OAuth/member and operator tokens cannot schedule. 403 scheduling_not_enabled when the capability is off. No automatic send-now fallback. Oldest creation first. Read and cancel remain available with scheduling disabled. Poll individual resources; restart pagination to discover new or changed statuses.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "enum": [
                "scheduled",
                "sending",
                "sent",
                "held",
                "cancelled",
                "failed",
                "delivery_unknown"
              ]
            }
          },
          {
            "name": "channel",
            "in": "query",
            "schema": {
              "enum": [
                "linkedin",
                "email",
                "x"
              ]
            }
          },
          {
            "name": "leadId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scheduledReplies": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "replyId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "leadId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "channel": {
                            "enum": [
                              "linkedin",
                              "email",
                              "x"
                            ]
                          },
                          "status": {
                            "enum": [
                              "scheduled",
                              "sending",
                              "sent",
                              "held",
                              "cancelled",
                              "failed",
                              "delivery_unknown"
                            ]
                          },
                          "reason": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "sendAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "nextAttemptAt": {
                            "type": "string"
                          },
                          "sentAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "text": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 10000
                          }
                        },
                        "required": [
                          "id",
                          "replyId",
                          "leadId",
                          "channel",
                          "status",
                          "reason",
                          "sendAt",
                          "nextAttemptAt",
                          "sentAt",
                          "version",
                          "text"
                        ]
                      }
                    },
                    "nextCursor": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "scheduledReplies",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/scheduled-replies/{id}": {
      "get": {
        "operationId": "getScheduledReply",
        "tags": [
          "Replies"
        ],
        "summary": "Read a scheduled reply",
        "description": "API-only private partner capability. Requires an enabled partner workspace/Team-owner key and optionally X-PumpGTM-User for its active child workspace. OAuth/member and operator tokens cannot schedule. 403 scheduling_not_enabled when the capability is off. No automatic send-now fallback. Sent means confirmed provider acceptance. Held needs explicit review. delivery_unknown must not be blindly retried or recreated; it reserves the conversation until reconciled.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scheduledReply": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "replyId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "leadId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "channel": {
                          "enum": [
                            "linkedin",
                            "email",
                            "x"
                          ]
                        },
                        "status": {
                          "enum": [
                            "scheduled",
                            "sending",
                            "sent",
                            "held",
                            "cancelled",
                            "failed",
                            "delivery_unknown"
                          ]
                        },
                        "reason": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "sendAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "nextAttemptAt": {
                          "type": "string"
                        },
                        "sentAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "text": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 10000
                        }
                      },
                      "required": [
                        "id",
                        "replyId",
                        "leadId",
                        "channel",
                        "status",
                        "reason",
                        "sendAt",
                        "nextAttemptAt",
                        "sentAt",
                        "version",
                        "text"
                      ]
                    }
                  },
                  "required": [
                    "scheduledReply"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "editScheduledReply",
        "tags": [
          "Replies"
        ],
        "summary": "Edit or reapprove an unsent reply",
        "description": "API-only private partner capability. Requires an enabled partner workspace/Team-owner key and optionally X-PumpGTM-User for its active child workspace. OAuth/member and operator tokens cannot schedule. 403 scheduling_not_enabled when the capability is off. No automatic send-now fallback. Only scheduled/held resources. Requires current expectedVersion; held also requires reapprove true. Changed conversation/account requires cancellation and fresh approval. 409 version_conflict, reapproval_required, conversation_changed or reply_not_editable.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[!-~]+$"
            },
            "description": "Reuse only for the identical create/edit request in this workspace."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sendAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Future RFC 3339 instant with Z or numeric offset, at most 30 days ahead. Earliest send time; the worker runs every minute."
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 10000
                  },
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "reapprove": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "sendAt",
                  "expectedVersion"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "scheduledReply": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "replyId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "leadId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "channel": {
                          "enum": [
                            "linkedin",
                            "email",
                            "x"
                          ]
                        },
                        "status": {
                          "enum": [
                            "scheduled",
                            "sending",
                            "sent",
                            "held",
                            "cancelled",
                            "failed",
                            "delivery_unknown"
                          ]
                        },
                        "reason": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "sendAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "nextAttemptAt": {
                          "type": "string"
                        },
                        "sentAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "text": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 10000
                        }
                      },
                      "required": [
                        "id",
                        "replyId",
                        "leadId",
                        "channel",
                        "status",
                        "reason",
                        "sendAt",
                        "nextAttemptAt",
                        "sentAt",
                        "version",
                        "text"
                      ]
                    }
                  },
                  "required": [
                    "ok",
                    "scheduledReply"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/scheduled-replies/{id}/cancel": {
      "post": {
        "operationId": "cancelScheduledReply",
        "tags": [
          "Replies"
        ],
        "summary": "Cancel before dispatch claims a reply",
        "description": "API-only private partner capability. Requires an enabled partner workspace/Team-owner key and optionally X-PumpGTM-User for its active child workspace. OAuth/member and operator tokens cannot schedule. 403 scheduling_not_enabled when the capability is off. No automatic send-now fallback. Idempotent. scheduled/held become cancelled. 409 once sending, sent, failed or delivery_unknown. Does not resume a Sequence or recall an in-flight message.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "scheduledReply": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "replyId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "leadId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "channel": {
                          "enum": [
                            "linkedin",
                            "email",
                            "x"
                          ]
                        },
                        "status": {
                          "enum": [
                            "scheduled",
                            "sending",
                            "sent",
                            "held",
                            "cancelled",
                            "failed",
                            "delivery_unknown"
                          ]
                        },
                        "reason": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "sendAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "nextAttemptAt": {
                          "type": "string"
                        },
                        "sentAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "text": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 10000
                        }
                      },
                      "required": [
                        "id",
                        "replyId",
                        "leadId",
                        "channel",
                        "status",
                        "reason",
                        "sendAt",
                        "nextAttemptAt",
                        "sentAt",
                        "version",
                        "text"
                      ]
                    }
                  },
                  "required": [
                    "ok",
                    "scheduledReply"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leads/{id}/reply-decisions": {
      "get": {
        "operationId": "getXReplyDecisionContext",
        "tags": [
          "Replies"
        ],
        "summary": "Get an X reply version without a draft",
        "description": "API-only private partner capability. Requires an enabled partner workspace/Team-owner key and optionally X-PumpGTM-User for its active child workspace. OAuth/member and operator tokens cannot schedule. 403 scheduling_not_enabled when the capability is off. No automatic send-now fallback. Returns an opaque version for the latest verified inbound event. 409 if history is unavailable, incomplete, or already answered. Does not decrypt bodies or send anything.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "leadId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "channel": {
                      "const": "x"
                    },
                    "replyVersion": {
                      "type": "string"
                    },
                    "allowedDecisions": {
                      "type": "array",
                      "items": {
                        "const": "send"
                      }
                    }
                  },
                  "required": [
                    "leadId",
                    "channel",
                    "replyVersion",
                    "allowedDecisions"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "scheduleDraftlessXReply",
        "tags": [
          "Replies"
        ],
        "summary": "Schedule a reply to a draft-less X conversation",
        "description": "API-only private partner capability. Requires an enabled partner workspace/Team-owner key and optionally X-PumpGTM-User for its active child workspace. OAuth/member and operator tokens cannot schedule. 403 scheduling_not_enabled when the capability is off. No automatic send-now fallback. Use replyVersion from GET on this path. Revalidates the latest inbound and exact sender before storing. 409 conversation_changed for stale context. Does not resume the Sequence.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[!-~]+$"
            },
            "description": "Reuse only for the identical create/edit request in this workspace."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channel": {
                    "const": "x"
                  },
                  "decision": {
                    "const": "send"
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 10000
                  },
                  "sendAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Future RFC 3339 instant with Z or numeric offset, at most 30 days ahead. Earliest send time; the worker runs every minute."
                  },
                  "replyVersion": {
                    "type": "string",
                    "minLength": 64,
                    "maxLength": 64
                  },
                  "by": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  }
                },
                "required": [
                  "channel",
                  "decision",
                  "text",
                  "sendAt",
                  "replyVersion"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "scheduledReply": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "replyId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "leadId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "channel": {
                          "enum": [
                            "linkedin",
                            "email",
                            "x"
                          ]
                        },
                        "status": {
                          "enum": [
                            "scheduled",
                            "sending",
                            "sent",
                            "held",
                            "cancelled",
                            "failed",
                            "delivery_unknown"
                          ]
                        },
                        "reason": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "sendAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "nextAttemptAt": {
                          "type": "string"
                        },
                        "sentAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "text": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 10000
                        }
                      },
                      "required": [
                        "id",
                        "replyId",
                        "leadId",
                        "channel",
                        "status",
                        "reason",
                        "sendAt",
                        "nextAttemptAt",
                        "sentAt",
                        "version",
                        "text"
                      ]
                    }
                  },
                  "required": [
                    "ok",
                    "scheduledReply"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/signup": {
      "post": {
        "operationId": "partnerSignup",
        "tags": [
          "Partner"
        ],
        "summary": "Create a partner account",
        "description": "Self-serve partner account for agent platforms and agencies; no browser step. The response carries the partner API key once (it is also the partner's MCP key). The email owns the account and can sign in later with a login link. acceptedPolicies must equal the current policy version. 409 email_in_use when the email already has an account: sign in and copy the key from the install page instead.",
        "parameters": [],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 254
                  },
                  "company": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "website": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2000
                  },
                  "acceptedPolicies": {
                    "const": "2026-09-18",
                    "description": "The current legal policy version, confirming acceptance of /terms and /privacy."
                  }
                },
                "required": [
                  "email",
                  "company",
                  "acceptedPolicies"
                ]
              },
              "example": {
                "email": "ops@agency.example",
                "company": "Example Agency",
                "website": "https://agency.example",
                "acceptedPolicies": "2026-09-18"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiKey": {
                      "type": "string"
                    },
                    "mcpUrlTemplate": {
                      "type": "string"
                    },
                    "freeLeads": {
                      "type": "integer"
                    },
                    "accountUrl": {
                      "type": "string"
                    },
                    "usersUrl": {
                      "type": "string"
                    },
                    "docsUrl": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "apiKey",
                    "mcpUrlTemplate",
                    "freeLeads",
                    "accountUrl",
                    "usersUrl",
                    "docsUrl"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/account": {
      "get": {
        "operationId": "getPartnerAccount",
        "tags": [
          "Partner"
        ],
        "summary": "Read the partner account, capabilities and usage",
        "description": "Partner id and name; enterprise capabilities enabled by PumpGTM (outreach, linkedinConnect); hosted connect-link settings; the REST policy for this key (rest.requireUserHeader); the MCP URL template; active user count; this period's leads, free allowance and billing state.",
        "parameters": [],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "partner": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name"
                      ]
                    },
                    "enterprise": {
                      "type": "object",
                      "properties": {
                        "outreach": {
                          "type": "boolean"
                        },
                        "linkedinConnect": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "outreach",
                        "linkedinConnect"
                      ]
                    },
                    "linkedinConnect": {
                      "type": "object",
                      "properties": {
                        "successRedirectUrl": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "failureRedirectUrl": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "brandName": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "successRedirectUrl",
                        "failureRedirectUrl",
                        "brandName"
                      ]
                    },
                    "rest": {
                      "type": "object",
                      "properties": {
                        "requireUserHeader": {
                          "type": "boolean",
                          "description": "When true, every /api/v1 request made with this partner key must carry X-PumpGTM-User; without it the request is 400 user_header_required instead of acting on the partner workspace. Default false."
                        }
                      },
                      "required": [
                        "requireUserHeader"
                      ]
                    },
                    "mcpUrlTemplate": {
                      "type": "string"
                    },
                    "users": {
                      "type": "integer"
                    },
                    "accounts": {
                      "type": "object",
                      "properties": {
                        "connected": {
                          "type": "integer"
                        },
                        "included": {
                          "anyOf": [
                            {
                              "type": "integer"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "remaining": {
                          "anyOf": [
                            {
                              "type": "integer"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "connected",
                        "included",
                        "remaining"
                      ]
                    },
                    "periodStart": {
                      "type": "string"
                    },
                    "leadsThisPeriod": {
                      "type": "integer"
                    },
                    "freeLeads": {
                      "type": "integer"
                    },
                    "freeLeadsRemaining": {
                      "type": "integer"
                    },
                    "billing": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "enum": [
                            "metered",
                            "billing_required",
                            "free"
                          ]
                        },
                        "checkoutUrl": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "status",
                        "checkoutUrl"
                      ]
                    }
                  },
                  "required": [
                    "partner",
                    "enterprise",
                    "linkedinConnect",
                    "rest",
                    "mcpUrlTemplate",
                    "users",
                    "accounts",
                    "periodStart",
                    "leadsThisPeriod",
                    "freeLeads",
                    "freeLeadsRemaining",
                    "billing"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updatePartnerAccount",
        "tags": [
          "Partner"
        ],
        "summary": "Set brand name, connect-link return URLs and the REST policy",
        "description": "Two groups, each behind its own capability (GET /account enterprise). Connect settings (enterprise.linkedinConnect): where end users land after a hosted LinkedIn connect link resolves, and the white-label name shown on that page (1-60 characters; null uses your workspace name). An absent field is kept, null or \"\" clears it. The end user id and link id are appended to the redirect as externalUserId and connectLinkId; only expired or revoked links use the failure URL. REST policy (enterprise.outreach): requireUserHeader true makes every /api/v1 request with this key that lacks X-PumpGTM-User fail with 400 user_header_required, so a missing header can never act on your own workspace; /api/partner/v1 and the per-user MCP URL are unaffected. Nothing is written when any group is refused. 400 { error, field } on a bad value (invalid_url, https_required, host_not_allowed, url_too_long, invalid_brand_name, invalid_require_user_header); 400 nothing_to_update or invalid_body with field null; 403 enterprise_required when the needed capability is off.",
        "parameters": [],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "successRedirectUrl": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 2000,
                        "description": "Absolute https URL to a public host, no credentials or fragment. null or \"\" clears it; an absent field is left as it is."
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "failureRedirectUrl": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 2000,
                        "description": "Absolute https URL to a public host, no credentials or fragment. null or \"\" clears it; an absent field is left as it is."
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "brandName": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 60
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "requireUserHeader": {
                    "type": "boolean"
                  }
                },
                "required": [],
                "minProperties": 1
              },
              "example": {
                "brandName": "Your Agency",
                "successRedirectUrl": "https://your-app.example/linkedin/done",
                "failureRedirectUrl": "https://your-app.example/linkedin/failed",
                "requireUserHeader": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "linkedinConnect": {
                      "type": "object",
                      "properties": {
                        "successRedirectUrl": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "failureRedirectUrl": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "brandName": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "successRedirectUrl",
                        "failureRedirectUrl",
                        "brandName"
                      ]
                    },
                    "rest": {
                      "type": "object",
                      "properties": {
                        "requireUserHeader": {
                          "type": "boolean",
                          "description": "When true, every /api/v1 request made with this partner key must carry X-PumpGTM-User; without it the request is 400 user_header_required instead of acting on the partner workspace. Default false."
                        }
                      },
                      "required": [
                        "requireUserHeader"
                      ]
                    }
                  },
                  "required": [
                    "linkedinConnect",
                    "rest"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users": {
      "get": {
        "operationId": "listPartnerUsers",
        "tags": [
          "Partner"
        ],
        "summary": "List end users with this period's usage",
        "description": "One row per end user with the same fields as GET /users/{externalUserId} (name, status, lead cap, mcpUrl, rest, outreach) plus people found and tool calls since periodStart, and last use.",
        "parameters": [],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "periodStart": {
                      "type": "string"
                    },
                    "users": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "externalUserId": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                            "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "status": {
                            "enum": [
                              "active",
                              "disabled"
                            ]
                          },
                          "monthlyLeadCap": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "minimum": 0,
                                "description": "People search cap for this user per period; null means no cap."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "mcpUrl": {
                            "type": "string",
                            "description": "https://mcp.pumpgtm.com/mcp/u/{externalUserId}"
                          },
                          "rest": {
                            "anyOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "header": {
                                    "const": "X-PumpGTM-User"
                                  },
                                  "value": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "header",
                                  "value"
                                ],
                                "description": "The header to add to /api/v1 requests to act for this user. null until outreach is enabled on the partner account."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "outreach": {
                            "enum": [
                              "enabled",
                              "disabled"
                            ],
                            "description": "disabled until PumpGTM enables outreach on the partner account."
                          },
                          "leadsFound": {
                            "type": "integer"
                          },
                          "toolCalls": {
                            "type": "integer"
                          },
                          "lastUsedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "externalUserId",
                          "name",
                          "createdAt",
                          "status",
                          "monthlyLeadCap",
                          "mcpUrl",
                          "rest",
                          "outreach",
                          "leadsFound",
                          "toolCalls",
                          "lastUsedAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "periodStart",
                    "users"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createPartnerUser",
        "tags": [
          "Partner"
        ],
        "summary": "Create an end user's workspace",
        "description": "Creates the isolated workspace for one end user before any MCP or REST traffic. Idempotent: 201 when created, 200 unchanged when the user already existed (monthlyLeadCap is then not applied; use PATCH). The response carries the user's mcpUrl (https://mcp.pumpgtm.com/mcp/u/{externalUserId}) and, once outreach is enabled on the partner account, rest: { header: \"X-PumpGTM-User\", value } and outreach: \"enabled\"; until then rest is null and outreach is \"disabled\". 400 invalid_external_user_id, 400 invalid_monthly_lead_cap.",
        "parameters": [],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "externalUserId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                    "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "monthlyLeadCap": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 0,
                        "description": "People search cap for this user per period; null means no cap."
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "externalUserId"
                ]
              },
              "example": {
                "externalUserId": "acme",
                "name": "Acme Robotics"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The user already existed; returned unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "externalUserId": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                      "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "status": {
                      "enum": [
                        "active",
                        "disabled"
                      ]
                    },
                    "monthlyLeadCap": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 0,
                          "description": "People search cap for this user per period; null means no cap."
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "mcpUrl": {
                      "type": "string",
                      "description": "https://mcp.pumpgtm.com/mcp/u/{externalUserId}"
                    },
                    "rest": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "header": {
                              "const": "X-PumpGTM-User"
                            },
                            "value": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "header",
                            "value"
                          ],
                          "description": "The header to add to /api/v1 requests to act for this user. null until outreach is enabled on the partner account."
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "outreach": {
                      "enum": [
                        "enabled",
                        "disabled"
                      ],
                      "description": "disabled until PumpGTM enables outreach on the partner account."
                    }
                  },
                  "required": [
                    "externalUserId",
                    "name",
                    "createdAt",
                    "status",
                    "monthlyLeadCap",
                    "mcpUrl",
                    "rest",
                    "outreach"
                  ]
                }
              }
            }
          },
          "201": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "externalUserId": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                      "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "status": {
                      "enum": [
                        "active",
                        "disabled"
                      ]
                    },
                    "monthlyLeadCap": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 0,
                          "description": "People search cap for this user per period; null means no cap."
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "mcpUrl": {
                      "type": "string",
                      "description": "https://mcp.pumpgtm.com/mcp/u/{externalUserId}"
                    },
                    "rest": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "header": {
                              "const": "X-PumpGTM-User"
                            },
                            "value": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "header",
                            "value"
                          ],
                          "description": "The header to add to /api/v1 requests to act for this user. null until outreach is enabled on the partner account."
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "outreach": {
                      "enum": [
                        "enabled",
                        "disabled"
                      ],
                      "description": "disabled until PumpGTM enables outreach on the partner account."
                    }
                  },
                  "required": [
                    "externalUserId",
                    "name",
                    "createdAt",
                    "status",
                    "monthlyLeadCap",
                    "mcpUrl",
                    "rest",
                    "outreach"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{externalUserId}": {
      "get": {
        "operationId": "getPartnerUser",
        "tags": [
          "Partner"
        ],
        "summary": "Read one end user",
        "description": "The user's status, lead cap, MCP URL and REST header. 404 user_not_found.",
        "parameters": [
          {
            "name": "externalUserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
              "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
            }
          }
        ],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "externalUserId": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                      "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "status": {
                      "enum": [
                        "active",
                        "disabled"
                      ]
                    },
                    "monthlyLeadCap": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 0,
                          "description": "People search cap for this user per period; null means no cap."
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "mcpUrl": {
                      "type": "string",
                      "description": "https://mcp.pumpgtm.com/mcp/u/{externalUserId}"
                    },
                    "rest": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "header": {
                              "const": "X-PumpGTM-User"
                            },
                            "value": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "header",
                            "value"
                          ],
                          "description": "The header to add to /api/v1 requests to act for this user. null until outreach is enabled on the partner account."
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "outreach": {
                      "enum": [
                        "enabled",
                        "disabled"
                      ],
                      "description": "disabled until PumpGTM enables outreach on the partner account."
                    }
                  },
                  "required": [
                    "externalUserId",
                    "name",
                    "createdAt",
                    "status",
                    "monthlyLeadCap",
                    "mcpUrl",
                    "rest",
                    "outreach"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updatePartnerUser",
        "tags": [
          "Partner"
        ],
        "summary": "Change a lead cap, disable or reactivate",
        "description": "monthlyLeadCap sets or clears (null) the user's people-search cap (400 invalid_monthly_lead_cap); status disabled is the same as DELETE (sequences paused, 403 user_disabled on MCP and REST, nothing more billed) and status active reactivates. At least one field is required (400 nothing_to_update; a non-object body is 400 invalid_body; both carry field null).",
        "parameters": [
          {
            "name": "externalUserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
              "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
            }
          }
        ],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "monthlyLeadCap": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 0,
                        "description": "People search cap for this user per period; null means no cap."
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "status": {
                    "enum": [
                      "active",
                      "disabled"
                    ]
                  }
                },
                "required": [],
                "minProperties": 1
              },
              "example": {
                "monthlyLeadCap": 250
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "externalUserId": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                      "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                    },
                    "status": {
                      "enum": [
                        "active",
                        "disabled"
                      ]
                    },
                    "monthlyLeadCap": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 0,
                          "description": "People search cap for this user per period; null means no cap."
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "externalUserId",
                    "status",
                    "monthlyLeadCap"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "disablePartnerUser",
        "tags": [
          "Partner"
        ],
        "summary": "Disable an end user",
        "description": "The user's workspace loses the partner's entitlement and Energy, its active sequences are paused, and its MCP URL and X-PumpGTM-User requests answer 403 user_disabled. Data is kept and nothing more is billed for them. PATCH { status: \"disabled\" } is equivalent; reactivate with PATCH { status: \"active\" }.",
        "parameters": [
          {
            "name": "externalUserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
              "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
            }
          }
        ],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "externalUserId": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                      "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                    },
                    "status": {
                      "enum": [
                        "active",
                        "disabled"
                      ]
                    },
                    "monthlyLeadCap": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 0,
                          "description": "People search cap for this user per period; null means no cap."
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "externalUserId",
                    "status",
                    "monthlyLeadCap"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{externalUserId}/linkedin/accounts": {
      "get": {
        "operationId": "listPartnerLinkedInAccounts",
        "tags": [
          "Partner"
        ],
        "summary": "List an end user's connected LinkedIn accounts",
        "description": "Enterprise. The user's LinkedIn identities with status (connected or disconnected) and display name. A saved connection does not prove live provider health. 404 user_not_found for a user that has not been created.",
        "parameters": [
          {
            "name": "externalUserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
              "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
            }
          }
        ],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accounts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "externalUserId": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                            "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                          },
                          "status": {
                            "enum": [
                              "connected",
                              "disconnected",
                              "pending",
                              "failed"
                            ],
                            "description": "connected or disconnected in steady state; treat anything but connected as not usable for sending."
                          },
                          "displayName": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "pictureUrl": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "connectedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "timezone": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "proxyCountry": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^[A-Z]{2}$",
                                "description": "Last recorded proxy country (ISO 3166-1 alpha-2), not a live location check, profile country or dedicated-IP guarantee. null means unknown."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "externalUserId",
                          "status",
                          "displayName",
                          "pictureUrl",
                          "connectedAt",
                          "timezone",
                          "proxyCountry"
                        ]
                      }
                    }
                  },
                  "required": [
                    "accounts"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{externalUserId}/linkedin/accounts/{accountId}": {
      "delete": {
        "operationId": "disconnectPartnerLinkedInAccount",
        "tags": [
          "Partner"
        ],
        "summary": "Disconnect one LinkedIn account",
        "description": "Enterprise. Sequences stop sending from this identity; its history is kept. Idempotent: an already disconnected account also returns 200. 404 user_not_found for a user that has not been created; 404 account_not_found; 503 disconnect_failed (retry in a minute).",
        "parameters": [
          {
            "name": "externalUserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
              "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
            }
          },
          {
            "name": "accountId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "externalUserId": {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                          "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                        },
                        "status": {
                          "const": "disconnected"
                        }
                      },
                      "required": [
                        "id",
                        "externalUserId",
                        "status"
                      ]
                    }
                  },
                  "required": [
                    "account"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/linkedin/accounts": {
      "get": {
        "operationId": "listLinkedInAccounts",
        "tags": [
          "Account"
        ],
        "summary": "List this workspace's LinkedIn senders",
        "description": "Saved connected and disconnected accounts; failed/pending connection attempts are excluded. Each id is the UUID for accountId on lead additions, sending limits and InMail credits. proxyCountry is the last recorded proxy country, not a live verification or an exclusive-IP guarantee. No provider requests, refreshes or sends. Use X-PumpGTM-User to select a partner client or authorized X-PumpGTM-Client Team delegation. inmailEnabled is the selected workspace's sending feature, independent of LinkedIn subscription or credit availability. Follow nextCursor until null; each cursor is just a position inside the currently authorized workspace. No-store.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "enum": [
                "connected",
                "disconnected"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accounts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "displayName": {
                            "type": "string"
                          },
                          "status": {
                            "enum": [
                              "connected",
                              "disconnected"
                            ]
                          },
                          "pictureUrl": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "connectedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "timezone": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "proxyCountry": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^[A-Z]{2}$",
                                "description": "Last recorded proxy country (ISO 3166-1 alpha-2), not a live location check, profile country or dedicated-IP guarantee. null means unknown."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "displayName",
                          "status",
                          "pictureUrl",
                          "connectedAt",
                          "timezone",
                          "proxyCountry"
                        ]
                      }
                    },
                    "inmailEnabled": {
                      "type": "boolean"
                    },
                    "nextCursor": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "uuid"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "hasMore": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "accounts",
                    "inmailEnabled",
                    "nextCursor",
                    "hasMore"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/linkedin/accounts/{accountId}/inmail-credits": {
      "get": {
        "operationId": "getLinkedInInmailCredits",
        "tags": [
          "Account"
        ],
        "summary": "Read one sender's live InMail credits",
        "description": "One live balance read from the sender in the authorized workspace. Pass its UUID from GET /linkedin/accounts. Returns each subscription's balance separately; null means no balance supplied, not zero. Reading neither enables InMail nor reserves credits, sends a message or guarantees a future send. Sending still needs the workspace feature and the sender's LinkedIn subscription. 404 account_not_found for absent/foreign accounts; 409 account_unavailable for disconnected or demo accounts; 429 rate_limited with Retry-After; 502 inmail_credits_unavailable for provider failure or malformed balances; 503 for an unavailable account read. Never substitutes zero for failure. No-store.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "accountId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accountId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "checkedAt": {
                      "type": "string"
                    },
                    "credits": {
                      "type": "object",
                      "properties": {
                        "premium": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "recruiter": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "salesNavigator": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "premium",
                        "recruiter",
                        "salesNavigator"
                      ]
                    }
                  },
                  "required": [
                    "accountId",
                    "checkedAt",
                    "credits"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "inmail_credits_unavailable: balance could not be read",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/linkedin/accounts/{accountId}/sending-limits": {
      "get": {
        "operationId": "getLinkedInSendingLimits",
        "tags": [
          "Account"
        ],
        "summary": "Read a LinkedIn account's daily invite cap and warm-up state",
        "description": "accountId is the LinkedIn sender UUID from GET /api/v1/linkedin/accounts (or GET /api/partner/v1/users/{id}/linkedin/accounts for a partner client). Returns the configured daily cap (1 to 30), the mode, warm-up progress, and the numbers the engine uses today: effective cap, invites already sent in the account's local day, and what remains. A week is bounded by 7 × the daily cap; there is no separate weekly setting. 404 account_not_found outside this workspace.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "accountId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accountId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "dailyInviteCap": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 30,
                      "description": "Configured full-pace cap: connection requests per account-local day once warm-up is over."
                    },
                    "mode": {
                      "enum": [
                        "warmup",
                        "outreach"
                      ]
                    },
                    "warmup": {
                      "type": "object",
                      "properties": {
                        "startedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "isWarming": {
                          "type": "boolean"
                        },
                        "daysRemaining": {
                          "type": "integer"
                        },
                        "ramp": {
                          "type": "array",
                          "items": {
                            "type": "integer"
                          }
                        }
                      },
                      "required": [
                        "startedAt",
                        "isWarming",
                        "daysRemaining",
                        "ramp"
                      ]
                    },
                    "effectiveDailyCapToday": {
                      "type": "integer",
                      "description": "What the engine will allow today: the warm-up ramp value or the configured cap, whichever is lower."
                    },
                    "invitesSentToday": {
                      "type": "integer"
                    },
                    "remainingToday": {
                      "type": "integer"
                    },
                    "workspaceDailyInviteCapTotal": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "description": "Workspace-wide ceiling across all connected accounts, when one is set."
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "limits": {
                      "type": "object",
                      "properties": {
                        "minDailyInviteCap": {
                          "type": "integer"
                        },
                        "maxDailyInviteCap": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "minDailyInviteCap",
                        "maxDailyInviteCap"
                      ]
                    }
                  },
                  "required": [
                    "accountId",
                    "dailyInviteCap",
                    "mode",
                    "warmup",
                    "effectiveDailyCapToday",
                    "invitesSentToday",
                    "remainingToday",
                    "workspaceDailyInviteCapTotal",
                    "limits"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "setLinkedInSendingLimits",
        "tags": [
          "Account"
        ],
        "summary": "Set a LinkedIn account's daily invite cap or warm-up mode",
        "description": "dailyInviteCap 1 to 30 (the same range as the dashboard). mode warmup restarts the 6-day ramp (5, 7, 10, 15, 16, 20 a day) and is always allowed; mode outreach graduates the account to its configured cap. Graduating while the ramp is still running is refused with 409 warmup_in_progress, because LinkedIn restricts fresh accounts that burst; send acknowledgeEarlyGraduation: true to do it anyway. Returns the same shape as GET after the change. 400 nothing_to_update with an empty body.",
        "parameters": [
          {
            "name": "X-PumpGTM-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace."
          },
          {
            "name": "X-PumpGTM-User",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
            },
            "description": "Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs."
          },
          {
            "name": "accountId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dailyInviteCap": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 30
                  },
                  "mode": {
                    "enum": [
                      "warmup",
                      "outreach"
                    ]
                  },
                  "acknowledgeEarlyGraduation": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "required": [],
                "additionalProperties": false
              },
              "example": {
                "dailyInviteCap": 20
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accountId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "dailyInviteCap": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 30,
                      "description": "Configured full-pace cap: connection requests per account-local day once warm-up is over."
                    },
                    "mode": {
                      "enum": [
                        "warmup",
                        "outreach"
                      ]
                    },
                    "warmup": {
                      "type": "object",
                      "properties": {
                        "startedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "isWarming": {
                          "type": "boolean"
                        },
                        "daysRemaining": {
                          "type": "integer"
                        },
                        "ramp": {
                          "type": "array",
                          "items": {
                            "type": "integer"
                          }
                        }
                      },
                      "required": [
                        "startedAt",
                        "isWarming",
                        "daysRemaining",
                        "ramp"
                      ]
                    },
                    "effectiveDailyCapToday": {
                      "type": "integer",
                      "description": "What the engine will allow today: the warm-up ramp value or the configured cap, whichever is lower."
                    },
                    "invitesSentToday": {
                      "type": "integer"
                    },
                    "remainingToday": {
                      "type": "integer"
                    },
                    "workspaceDailyInviteCapTotal": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "description": "Workspace-wide ceiling across all connected accounts, when one is set."
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "limits": {
                      "type": "object",
                      "properties": {
                        "minDailyInviteCap": {
                          "type": "integer"
                        },
                        "maxDailyInviteCap": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "minDailyInviteCap",
                        "maxDailyInviteCap"
                      ]
                    }
                  },
                  "required": [
                    "accountId",
                    "dailyInviteCap",
                    "mode",
                    "warmup",
                    "effectiveDailyCapToday",
                    "invitesSentToday",
                    "remainingToday",
                    "workspaceDailyInviteCapTotal",
                    "limits"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "{ error: \"warmup_in_progress\", message }: the ramp has not finished and acknowledgeEarlyGraduation was not true; nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{externalUserId}/linkedin/connect-links": {
      "post": {
        "operationId": "createPartnerConnectLink",
        "tags": [
          "Partner"
        ],
        "summary": "Mint a hosted LinkedIn connect link",
        "description": "409 account_limit_reached when every LinkedIn account included in your plan is already connected (see accounts on GET /account). Enterprise. Returns a PumpGTM-hosted url (shown once, never stored in clear) where this end user signs in to LinkedIn themselves; open it in a popup, never an iframe. Links are single use and expire after 7 days by default (expiresInMinutes 10 to 43200). Completion is announced through your linkedin.connected webhook and the redirect URLs from PATCH /account; GET the link to poll. Webhook, redirect and poll have no ordering guarantee: treat all three as idempotent on connectLink.id. This route creates the user's workspace if it does not exist yet. A user may hold at most 10 open links (409 connect_link_limit_reached). 400 invalid_expires_in_minutes with field. A 409 saying the link cannot be minted because of a problem with your partner account creates nothing; contact PumpGTM rather than retrying.",
        "parameters": [
          {
            "name": "externalUserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
              "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
            }
          }
        ],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expiresInMinutes": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 10,
                        "maximum": 43200
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [],
                "additionalProperties": false
              },
              "example": {
                "expiresInMinutes": 10080
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connectLink": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "externalUserId": {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                          "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                        },
                        "status": {
                          "enum": [
                            "pending",
                            "connected",
                            "expired",
                            "revoked"
                          ],
                          "description": "expired and revoked are final; mint a new link."
                        },
                        "expiresAt": {
                          "type": "string"
                        },
                        "connectedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "revokedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "createdAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "externalUserId",
                        "status",
                        "expiresAt",
                        "connectedAt",
                        "revokedAt",
                        "createdAt"
                      ]
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "connectLink",
                    "url"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listPartnerConnectLinks",
        "tags": [
          "Partner"
        ],
        "summary": "List an end user's connect links",
        "description": "Enterprise. Newest first, at most 25. The hosted url is never returned again. 404 user_not_found for a user that has not been created.",
        "parameters": [
          {
            "name": "externalUserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
              "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
            }
          }
        ],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connectLinks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "externalUserId": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                            "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                          },
                          "status": {
                            "enum": [
                              "pending",
                              "connected",
                              "expired",
                              "revoked"
                            ],
                            "description": "expired and revoked are final; mint a new link."
                          },
                          "expiresAt": {
                            "type": "string"
                          },
                          "connectedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "revokedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "externalUserId",
                          "status",
                          "expiresAt",
                          "connectedAt",
                          "revokedAt",
                          "createdAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "connectLinks"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{externalUserId}/linkedin/connect-links/{linkId}": {
      "get": {
        "operationId": "getPartnerConnectLink",
        "tags": [
          "Partner"
        ],
        "summary": "Poll one connect link",
        "description": "Enterprise. status is pending, connected, expired or revoked (expired and revoked are final). Polling rule: every 3 seconds, stop when status is not pending, give up after 15 minutes; this GET is not rate limited. 404 connect_link_not_found; 404 user_not_found for a user that has not been created.",
        "parameters": [
          {
            "name": "externalUserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
              "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
            }
          },
          {
            "name": "linkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connectLink": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "externalUserId": {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                          "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                        },
                        "status": {
                          "enum": [
                            "pending",
                            "connected",
                            "expired",
                            "revoked"
                          ],
                          "description": "expired and revoked are final; mint a new link."
                        },
                        "expiresAt": {
                          "type": "string"
                        },
                        "connectedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "revokedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "createdAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "externalUserId",
                        "status",
                        "expiresAt",
                        "connectedAt",
                        "revokedAt",
                        "createdAt"
                      ]
                    }
                  },
                  "required": [
                    "connectLink"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "revokePartnerConnectLink",
        "tags": [
          "Partner"
        ],
        "summary": "Revoke an open connect link",
        "description": "Enterprise. Only a pending link can be revoked; already connected, expired or revoked links return 409 connect_link_not_pending with the current link. 404 connect_link_not_found; 404 user_not_found for a user that has not been created.",
        "parameters": [
          {
            "name": "externalUserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
              "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
            }
          },
          {
            "name": "linkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "servers": [
          {
            "url": "https://app.pumpgtm.com/api/partner/v1",
            "description": "Partner API (partner workspace key)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Read outcome fields; success does not imply delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": {
                      "type": "boolean"
                    },
                    "connectLink": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "externalUserId": {
                              "type": "string",
                              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$",
                              "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters."
                            },
                            "status": {
                              "enum": [
                                "pending",
                                "connected",
                                "expired",
                                "revoked"
                              ],
                              "description": "expired and revoked are final; mint a new link."
                            },
                            "expiresAt": {
                              "type": "string"
                            },
                            "connectedAt": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "revokedAt": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "createdAt": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "id",
                            "externalUserId",
                            "status",
                            "expiresAt",
                            "connectedAt",
                            "revokedAt",
                            "createdAt"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "revoked",
                    "connectLink"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Revision, identity or state conflict: { error, message } and nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; respect Retry-After when provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; identity may be unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        },
        "additionalProperties": true,
        "required": [
          "error"
        ],
        "description": "Every error response. error is a stable machine-readable code (for example invalid_request, sequence_not_active, energy_exhausted); message is plain language for a person."
      }
    },
    "securitySchemes": {
      "WorkspaceKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Workspace MCP key",
        "description": "Keep the key in a server-side secret. Do not send Pump keys to X or data vendors. For partners this is the partner workspace key from signup (shown and rotated on /api-keys): it authenticates /api/partner/v1 and, with X-PumpGTM-User, acts on an end user's workspace under /api/v1. Only a workspace key or a Team owner key can act for end users; a personal key issued through an OAuth sign-in gets 403 partner_key_required."
      }
    }
  }
}
