{
  "swagger": "2.0",
  "info": {
    "title": "Plyne API",
    "description": "Read Signal Agents, Leads, Accounts, and their historical signals using the same concepts as the Plyne portal.",
    "version": "1.0.0"
  },
  "tags": [
    {
      "name": "SignalsService"
    }
  ],
  "host": "api.plyne.ai",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/v1/accounts/search": {
      "post": {
        "summary": "Accounts",
        "description": "Read Accounts with their selected evaluation, linked findings, qualification, and AI score.",
        "operationId": "SignalsService_ListAccounts",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1ListAccountsResponse"
            }
          },
          "default": {
            "description": "Application error. The code is a string; HTTP status indicates the failure category.",
            "schema": {
              "$ref": "#/definitions/v1APIError"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/v1ListAccountsRequest"
            }
          }
        ],
        "tags": [
          "Accounts"
        ]
      }
    },
    "/v1/accounts/{account_id}/evaluations/search": {
      "post": {
        "summary": "Account evaluations",
        "description": "Read saved evaluations and their exact linked findings, newest evaluation first.",
        "operationId": "SignalsService_ListAccountEvaluations",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1ListAccountEvaluationsResponse"
            }
          }
        },
        "parameters": [
          {
            "name": "account_id",
            "description": "Required Account ID returned by the corresponding list endpoint.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SignalsServiceListAccountEvaluationsBody"
            }
          }
        ],
        "tags": [
          "Accounts"
        ]
      }
    },
    "/v1/accounts/{account_id}/signals/search": {
      "post": {
        "summary": "Read Account signal history",
        "description": "Read stored material findings, including older and unqualified findings, newest found_at first. Existing historical findings require no regeneration.",
        "operationId": "SignalsService_ListAccountSignals",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1ListAccountSignalsResponse"
            }
          },
          "default": {
            "description": "Application error. The code is a string; HTTP status indicates the failure category.",
            "schema": {
              "$ref": "#/definitions/v1APIError"
            }
          }
        },
        "parameters": [
          {
            "name": "account_id",
            "description": "Required Account ID returned by an Account search. REST supplies it in the URL path; MCP supplies it as the account_id tool argument.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SignalsServiceListAccountSignalsBody"
            }
          }
        ],
        "tags": [
          "Accounts"
        ]
      }
    },
    "/v1/leads/search": {
      "post": {
        "summary": "Leads",
        "description": "Read Leads with account details and the selected evaluation with linked findings. Date found, Latest signal, and AI score match portal semantics.",
        "operationId": "SignalsService_ListLeads",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1ListLeadsResponse"
            }
          },
          "default": {
            "description": "Application error. The code is a string; HTTP status indicates the failure category.",
            "schema": {
              "$ref": "#/definitions/v1APIError"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/v1ListLeadsRequest"
            }
          }
        ],
        "tags": [
          "Leads"
        ]
      }
    },
    "/v1/leads/{lead_id}/evaluations/search": {
      "post": {
        "summary": "Lead evaluations",
        "description": "Read saved evaluations and their exact linked findings, newest evaluation first.",
        "operationId": "SignalsService_ListLeadEvaluations",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1ListLeadEvaluationsResponse"
            }
          }
        },
        "parameters": [
          {
            "name": "lead_id",
            "description": "Required Lead ID returned by the corresponding list endpoint.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SignalsServiceListLeadEvaluationsBody"
            }
          }
        ],
        "tags": [
          "Leads"
        ]
      }
    },
    "/v1/leads/{lead_id}/signals/search": {
      "post": {
        "summary": "Read Lead signal history",
        "description": "Read stored material findings, including older and unqualified findings, newest found_at first. This is signal history, not an audit log of every check.",
        "operationId": "SignalsService_ListLeadSignals",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1ListLeadSignalsResponse"
            }
          },
          "default": {
            "description": "Application error. The code is a string; HTTP status indicates the failure category.",
            "schema": {
              "$ref": "#/definitions/v1APIError"
            }
          }
        },
        "parameters": [
          {
            "name": "lead_id",
            "description": "Required Lead ID returned by a Lead search. REST supplies it in the URL path; MCP supplies it as the lead_id tool argument.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SignalsServiceListLeadSignalsBody"
            }
          }
        ],
        "tags": [
          "Leads"
        ]
      }
    },
    "/v1/signal-agents": {
      "get": {
        "summary": "List Signal Agents",
        "description": "Read non-archived Signal Agents configured in the portal, newest first.",
        "operationId": "SignalsService_ListSignalAgents",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1ListSignalAgentsResponse"
            }
          },
          "default": {
            "description": "Application error. The code is a string; HTTP status indicates the failure category.",
            "schema": {
              "$ref": "#/definitions/v1APIError"
            }
          }
        },
        "parameters": [
          {
            "name": "limit",
            "description": "Page size from 1 to 100. Omit for the default of 50; explicit zero is rejected on this GET endpoint.",
            "in": "query",
            "required": false,
            "type": "integer",
            "format": "int64"
          },
          {
            "name": "after",
            "description": "Opaque next cursor returned by the previous response. Keep the same organization and filters.",
            "in": "query",
            "required": false,
            "type": "string"
          },
          {
            "name": "agent_ids",
            "description": "Return only these configured Signal Agent IDs. Omit to include all matching non-archived agents.",
            "in": "query",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            },
            "collectionFormat": "multi"
          },
          {
            "name": "statuses",
            "description": "Filter by recurring schedule status: active or paused. Values are case-insensitive.",
            "in": "query",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            },
            "collectionFormat": "multi"
          }
        ],
        "tags": [
          "Signal Agents"
        ]
      }
    }
  },
  "definitions": {
    "SignalsServiceListAccountEvaluationsBody": {
      "type": "object",
      "properties": {
        "cursor": {
          "$ref": "#/definitions/v1CursorRequest",
          "description": "Page size and continuation cursor. Default 50, maximum 100."
        },
        "sheet_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter evaluations by their source Sheet IDs.",
          "maxItems": 100
        },
        "found_at": {
          "$ref": "#/definitions/v1TimeRange",
          "description": "Filter by the evaluation's saved time. Omit to include older evaluations."
        }
      }
    },
    "SignalsServiceListAccountSignalsBody": {
      "type": "object",
      "properties": {
        "cursor": {
          "$ref": "#/definitions/v1CursorRequest",
          "description": "Page size and opaque cursor. Omit for the first page with 50 records."
        },
        "signal_types": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by signal types. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "sheet_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by sheet ids. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "found_at": {
          "$ref": "#/definitions/v1TimeRange",
          "description": "Date found range. On entity lists this is first Directory appearance; on signal history it is the saved finding timestamp."
        },
        "evaluation_id": {
          "type": "string",
          "description": "Return findings linked to this exact evaluation ID. Keep it unchanged while paging. Omit to read all visible signal findings.",
          "maxLength": 256
        }
      }
    },
    "SignalsServiceListLeadEvaluationsBody": {
      "type": "object",
      "properties": {
        "cursor": {
          "$ref": "#/definitions/v1CursorRequest",
          "description": "Page size and continuation cursor. Default 50, maximum 100."
        },
        "sheet_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter evaluations by their source Sheet IDs.",
          "maxItems": 100
        },
        "found_at": {
          "$ref": "#/definitions/v1TimeRange",
          "description": "Filter by the evaluation's saved time. Omit to include older evaluations."
        }
      }
    },
    "SignalsServiceListLeadSignalsBody": {
      "type": "object",
      "properties": {
        "cursor": {
          "$ref": "#/definitions/v1CursorRequest",
          "description": "Page size and opaque cursor. Omit for the first page with 50 records."
        },
        "signal_types": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by signal types. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "sheet_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by sheet ids. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "found_at": {
          "$ref": "#/definitions/v1TimeRange",
          "description": "Date found range. On entity lists this is first Directory appearance; on signal history it is the saved finding timestamp."
        },
        "evaluation_id": {
          "type": "string",
          "description": "Return findings linked to this exact evaluation ID. Keep it unchanged while paging. Omit to read all visible signal findings.",
          "maxLength": 256
        }
      }
    },
    "v1APIError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "example": "invalid_argument",
          "description": "Machine-readable Connect error code, such as invalid_argument, unauthenticated, permission_denied, resource_exhausted, or internal."
        },
        "message": {
          "type": "string",
          "example": "limit must be between 1 and 100",
          "description": "Human-readable explanation. Internal diagnostics are not exposed."
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Optional Connect error details. Each detail may contain a protobuf type name, base64 value, and decoded debug object. Omitted when no details are attached."
        }
      },
      "description": "Application error returned by the public API using Connect JSON error semantics.",
      "required": [
        "code"
      ]
    },
    "v1Account": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "co_acme",
          "description": "Stable Account identifier; use this ID to read Account signal history."
        },
        "name": {
          "type": "string",
          "example": "Acme",
          "description": "Company display name; empty string when unavailable."
        },
        "domain": {
          "type": "string",
          "example": "acme.com",
          "description": "Company domain without a scheme; empty string when unavailable."
        },
        "profile": {
          "$ref": "#/definitions/v1Profile",
          "description": "Company LinkedIn profile, or null when unavailable.",
          "x-nullable": true
        },
        "country_code": {
          "type": "string",
          "example": "US",
          "description": "Company country as an ISO 3166-1 alpha-2 code; empty string when unavailable."
        },
        "source_sheet": {
          "$ref": "#/definitions/v1Sheet",
          "description": "Source Sheet for the selected row, or null. This is not the complete list of Sheet memberships.",
          "x-nullable": true
        },
        "evaluation": {
          "$ref": "#/definitions/v1Evaluation",
          "description": "Selected portal evaluation and a page of its exact linked findings, or null. Qualification and AI score are returned only inside this evaluation.",
          "x-nullable": true
        },
        "found_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-08-01T08:00:00Z",
          "description": "When the Account first entered the portal Directory. This is entity-level Date found, not the selected finding date.",
          "x-nullable": true
        },
        "latest_signal_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-11-15T08:00:00Z",
          "description": "Time the latest visible material occurrence was saved for this entity, including rejected or unclear findings. Null when none exists. Source filters do not reduce this entity-wide statistic.",
          "x-nullable": true
        },
        "signal_count": {
          "type": "integer",
          "format": "int32",
          "example": 3,
          "description": "Number of independently configured qualified signal sources across this entity. Repeated findings for one type, Sheet, and agent configuration count once. This is not the history-entry count.",
          "minimum": -1,
          "exclusiveMinimum": true
        },
        "signal_sources": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1SignalSource"
          },
          "description": "Qualified source identities shown in the portal signal stack. Grouped by type, Sheet, and Signal Agent; not the complete finding history. Uses the same source set as signal_count."
        }
      },
      "required": [
        "id",
        "name",
        "domain",
        "profile",
        "country_code",
        "source_sheet",
        "evaluation",
        "signal_sources",
        "found_at",
        "latest_signal_at",
        "signal_count"
      ]
    },
    "v1AccountSummary": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "co_acme",
          "description": "Stable Account identifier; use this ID with the Accounts and Account signal history endpoints."
        },
        "name": {
          "type": "string",
          "example": "Acme",
          "description": "Company display name; empty string when unavailable."
        },
        "domain": {
          "type": "string",
          "example": "acme.com",
          "description": "Company domain without a scheme; empty string when unavailable."
        },
        "linkedin_url": {
          "type": "string",
          "example": "https://www.linkedin.com/company/acme",
          "description": "Company LinkedIn profile URL; empty string when unavailable."
        },
        "country_code": {
          "type": "string",
          "example": "US",
          "description": "Company country as an ISO 3166-1 alpha-2 code; empty string when unavailable."
        }
      },
      "required": [
        "id",
        "name",
        "domain",
        "linkedin_url",
        "country_code"
      ]
    },
    "v1CursorRequest": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "format": "int64",
          "example": 50,
          "description": "Page size. Omitted or 0 uses the default of 50; values above 100 are rejected.",
          "maximum": 100,
          "minimum": -1,
          "exclusiveMinimum": true
        },
        "after": {
          "type": "string",
          "example": "",
          "description": "Opaque next cursor returned by the previous response. Keep the same organization, resource, filters, and sort.",
          "maxLength": 4096
        }
      }
    },
    "v1CursorResponse": {
      "type": "object",
      "properties": {
        "next": {
          "type": "string",
          "example": "",
          "description": "Opaque cursor for the next page; empty string on the final page."
        },
        "has_more": {
          "type": "boolean",
          "example": false,
          "description": "Whether another page of matching records is available."
        }
      },
      "required": [
        "next",
        "has_more"
      ]
    },
    "v1Evaluation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Saved evaluation occurrence ID. Use it as evaluation_id on signal history to retrieve its linked findings."
        },
        "found_at": {
          "type": "string",
          "format": "date-time",
          "description": "When this evaluation was saved. Evaluations can be refreshed and are not immutable revisions."
        },
        "source_sheet": {
          "$ref": "#/definitions/v1Sheet",
          "description": "Source Sheet for this evaluation, or null.",
          "x-nullable": true
        },
        "signal_agent_id": {
          "type": "string",
          "description": "Signal Agent associated with this evaluation; empty string when unavailable."
        },
        "qualification": {
          "$ref": "#/definitions/v1Qualification",
          "description": "This evaluation's recorded qualification, or null. It is not copied from a different evaluation.",
          "x-nullable": true
        },
        "ai_score": {
          "$ref": "#/definitions/v1Score",
          "description": "This evaluation's recorded score, or null when uncalculated.",
          "x-nullable": true
        },
        "findings": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1SignalHistoryEntry"
          },
          "description": "Up to 5 visible findings linked to this exact evaluation, newest saved first. Each retains its own assessment and evidence. An independently evaluated finding can appear here as itself.",
          "maxItems": 5
        },
        "findings_cursor": {
          "$ref": "#/definitions/v1CursorResponse",
          "description": "Continue via the corresponding signal history endpoint using evaluation_id equal to this evaluation's id and cursor.after equal to next. Keep other filters unset. Always present."
        }
      },
      "required": [
        "id",
        "found_at",
        "source_sheet",
        "signal_agent_id",
        "qualification",
        "ai_score",
        "findings",
        "findings_cursor"
      ]
    },
    "v1Lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "ld_person",
          "description": "Stable Lead identifier; use this ID to read Lead signal history."
        },
        "full_name": {
          "type": "string",
          "example": "Sarah Carter",
          "description": "First and last name joined for display. Uses Unknown person when no name is recorded."
        },
        "job_title": {
          "type": "string",
          "example": "Head of Engineering",
          "description": "Current selected job title; empty string when unavailable."
        },
        "profile": {
          "$ref": "#/definitions/v1Profile",
          "description": "Selected person profile, or null when no profile details are available.",
          "x-nullable": true
        },
        "account": {
          "$ref": "#/definitions/v1AccountSummary",
          "description": "Associated company summary, or null when no Account is available. This is a compact AccountSummary rather than the full Account response.",
          "x-nullable": true
        },
        "source_sheet": {
          "$ref": "#/definitions/v1Sheet",
          "description": "Source Sheet for the selected row, or null. This is not the complete list of Sheet memberships.",
          "x-nullable": true
        },
        "evaluation": {
          "$ref": "#/definitions/v1Evaluation",
          "description": "Selected portal evaluation and a page of its exact linked findings, or null. Qualification and AI score are returned only inside this evaluation.",
          "x-nullable": true
        },
        "country_code": {
          "type": "string",
          "example": "US",
          "description": "Lead country as an ISO 3166-1 alpha-2 code; empty string when unavailable."
        },
        "found_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-08-01T08:00:00Z",
          "description": "When the Lead first entered the portal Directory. This is entity-level Date found, not the selected finding date.",
          "x-nullable": true
        },
        "latest_signal_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-11-15T08:00:00Z",
          "description": "Time the latest visible material occurrence was saved for this entity, including rejected or unclear findings. Null when none exists. Source filters do not reduce this entity-wide statistic.",
          "x-nullable": true
        },
        "signal_count": {
          "type": "integer",
          "format": "int32",
          "example": 3,
          "description": "Number of independently configured qualified signal sources across this entity. Repeated findings for one type, Sheet, and agent configuration count once. This is not the history-entry count.",
          "minimum": -1,
          "exclusiveMinimum": true
        },
        "signal_sources": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1SignalSource"
          },
          "description": "Qualified source identities shown in the portal signal stack. Grouped by type, Sheet, and Signal Agent; not the complete finding history. Uses the same source set as signal_count."
        }
      },
      "required": [
        "id",
        "full_name",
        "job_title",
        "profile",
        "account",
        "source_sheet",
        "evaluation",
        "signal_sources",
        "country_code",
        "found_at",
        "latest_signal_at",
        "signal_count"
      ]
    },
    "v1ListAccountEvaluationsResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1Evaluation"
          },
          "description": "One page of saved evaluations, including older decisions. Always an array."
        },
        "cursor": {
          "$ref": "#/definitions/v1CursorResponse",
          "description": "Continuation cursor bound to the workspace, entity, evaluation resource, and filters. Always present."
        }
      },
      "required": [
        "data",
        "cursor"
      ]
    },
    "v1ListAccountSignalsResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1SignalHistoryEntry"
          },
          "description": "Records on this page. Always an array, including when no records match."
        },
        "cursor": {
          "$ref": "#/definitions/v1CursorResponse",
          "description": "Pagination metadata. Always present; next is empty and has_more is false on the final page."
        }
      },
      "required": [
        "data",
        "cursor"
      ]
    },
    "v1ListAccountsRequest": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "example": "Stripe",
          "description": "Case-insensitive literal substring of the company name. Omit for no text filter. Maximum 200 characters. Percent and underscore are treated literally.",
          "maxLength": 200
        },
        "account_domains": {
          "type": "array",
          "example": [
            "stripe.com"
          ],
          "items": {
            "type": "string"
          },
          "description": "Exact company domains, normalized to lowercase without www. URLs are accepted and reduced to their host; subdomains remain distinct. At most 100 values, each at most 256 characters before normalization.",
          "maxItems": 100
        },
        "cursor": {
          "$ref": "#/definitions/v1CursorRequest",
          "description": "Page size and opaque cursor. Omit for the first page with 50 records."
        },
        "account_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by account ids. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "signal_types": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by signal types. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "country_codes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by country codes. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "sheet_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by sheet ids. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "found_at": {
          "$ref": "#/definitions/v1TimeRange",
          "description": "Date found range. On entity lists this is first Directory appearance; on signal history it is the saved finding timestamp."
        },
        "latest_signal_at": {
          "$ref": "#/definitions/v1TimeRange",
          "description": "Range for the entity-wide latest visible material signal timestamp, including rejected or unclear findings."
        },
        "ai_score": {
          "$ref": "#/definitions/v1ScoreRange",
          "description": "Inclusive AI score bounds from 0 to 100. min must not exceed max."
        },
        "sort": {
          "$ref": "#/definitions/v1Sort",
          "description": "Ordering for the entity list. Default is found_at descending."
        }
      }
    },
    "v1ListAccountsResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1Account"
          },
          "description": "Records on this page. Always an array, including when no records match."
        },
        "cursor": {
          "$ref": "#/definitions/v1CursorResponse",
          "description": "Pagination metadata. Always present; next is empty and has_more is false on the final page."
        }
      },
      "required": [
        "data",
        "cursor"
      ]
    },
    "v1ListLeadEvaluationsResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1Evaluation"
          },
          "description": "One page of saved evaluations, including older decisions. Always an array."
        },
        "cursor": {
          "$ref": "#/definitions/v1CursorResponse",
          "description": "Continuation cursor bound to the workspace, entity, evaluation resource, and filters. Always present."
        }
      },
      "required": [
        "data",
        "cursor"
      ]
    },
    "v1ListLeadSignalsResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1SignalHistoryEntry"
          },
          "description": "Records on this page. Always an array, including when no records match."
        },
        "cursor": {
          "$ref": "#/definitions/v1CursorResponse",
          "description": "Pagination metadata. Always present; next is empty and has_more is false on the final page."
        }
      },
      "required": [
        "data",
        "cursor"
      ]
    },
    "v1ListLeadsRequest": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "example": "Jamie",
          "description": "Case-insensitive literal substring of the person's full name or associated company name. Omit for no text filter. Maximum 200 characters. Percent and underscore are treated literally.",
          "maxLength": 200
        },
        "account_domains": {
          "type": "array",
          "example": [
            "stripe.com"
          ],
          "items": {
            "type": "string"
          },
          "description": "Exact associated company domains, normalized to lowercase without www. URLs are accepted and reduced to their host; subdomains remain distinct. At most 100 values, each at most 256 characters before normalization.",
          "maxItems": 100
        },
        "cursor": {
          "$ref": "#/definitions/v1CursorRequest",
          "description": "Page size and opaque cursor. Omit for the first page with 50 records."
        },
        "lead_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by lead ids. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "signal_types": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by signal types. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "account_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by account ids. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "latest_signal_at": {
          "$ref": "#/definitions/v1TimeRange",
          "description": "Range for the entity-wide latest visible material signal timestamp, including rejected or unclear findings."
        },
        "sort": {
          "$ref": "#/definitions/v1Sort",
          "description": "Ordering for the entity list. Default is found_at descending."
        },
        "lead_country_codes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by lead country codes. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "account_country_codes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by account country codes. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "sheet_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Filter by sheet ids. Omit to leave this filter unrestricted. Values must be nonempty and at most 256 characters.",
          "maxItems": 100
        },
        "found_at": {
          "$ref": "#/definitions/v1TimeRange",
          "description": "Date found range. On entity lists this is first Directory appearance; on signal history it is the saved finding timestamp."
        },
        "ai_score": {
          "$ref": "#/definitions/v1ScoreRange",
          "description": "Inclusive AI score bounds from 0 to 100. min must not exceed max."
        }
      }
    },
    "v1ListLeadsResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1Lead"
          },
          "description": "Records on this page. Always an array, including when no records match."
        },
        "cursor": {
          "$ref": "#/definitions/v1CursorResponse",
          "description": "Pagination metadata. Always present; next is empty and has_more is false on the final page."
        }
      },
      "required": [
        "data",
        "cursor"
      ]
    },
    "v1ListSignalAgentsResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1SignalAgent"
          },
          "description": "Records on this page. Always an array, including when no records match."
        },
        "cursor": {
          "$ref": "#/definitions/v1CursorResponse",
          "description": "Pagination metadata. Always present; next is empty and has_more is false on the final page."
        }
      },
      "required": [
        "data",
        "cursor"
      ]
    },
    "v1Profile": {
      "type": "object",
      "properties": {
        "platform": {
          "type": "string",
          "example": "linkedin",
          "description": "Profile source platform; empty string when unavailable. Values can include linkedin, facebook, and reddit."
        },
        "url": {
          "type": "string",
          "example": "https://www.linkedin.com/in/example",
          "description": "Profile URL; empty string when unavailable."
        }
      },
      "required": [
        "platform",
        "url"
      ]
    },
    "v1Qualification": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "example": "qualified",
          "description": "Recorded qualification status. Known values are qualified, unqualified, unclear, and error; empty string when no status was recorded."
        },
        "reason": {
          "type": "string",
          "example": "Matches the target customer profile.",
          "description": "Short explanation of the qualification decision; empty string when unavailable."
        },
        "reasoning": {
          "type": "string",
          "example": "Role and account context match the configured ICP.",
          "description": "Detailed explanation recorded for this qualification; empty string when unavailable."
        },
        "references": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1Reference"
          },
          "description": "Source links attached to this qualification decision, distinct from signal finding evidence. At most 20 distinct URLs; empty array when none are available.",
          "maxItems": 20
        }
      },
      "required": [
        "status",
        "reason",
        "reasoning",
        "references"
      ]
    },
    "v1Reference": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "example": "evidence",
          "description": "Reference category. Public evidence links currently use evidence."
        },
        "label": {
          "type": "string",
          "example": "Evidence source",
          "description": "Human-readable source label."
        },
        "url": {
          "type": "string",
          "example": "https://example.com/source",
          "description": "Source URL associated with this record."
        }
      },
      "required": [
        "type",
        "label",
        "url"
      ]
    },
    "v1Score": {
      "type": "object",
      "properties": {
        "value": {
          "type": "integer",
          "format": "int32",
          "example": 86,
          "description": "Calculated AI score from 0 to 100. A score of zero is valid; the parent ai_score object is null when no score has been calculated.",
          "maximum": 100,
          "minimum": -1,
          "exclusiveMinimum": true
        },
        "fit": {
          "type": "string",
          "example": "high",
          "enum": [
            "weak",
            "low",
            "medium",
            "high"
          ],
          "description": "Score band: weak for 0-29, low for 30-49, medium for 50-79, high for 80-100."
        },
        "reasoning": {
          "type": "string",
          "example": "Strong role fit and relevant signal evidence.",
          "description": "Explanation associated with this calculated score; empty string when unavailable."
        }
      },
      "required": [
        "value",
        "fit",
        "reasoning"
      ]
    },
    "v1ScoreRange": {
      "type": "object",
      "properties": {
        "min": {
          "type": "integer",
          "format": "int32",
          "example": 0,
          "description": "Inclusive lower AI score bound. Omit this field for no lower bound.",
          "maximum": 100,
          "minimum": -1,
          "exclusiveMinimum": true
        },
        "max": {
          "type": "integer",
          "format": "int32",
          "example": 100,
          "description": "Inclusive upper AI score bound. Omit this field for no upper bound.",
          "maximum": 100,
          "minimum": -1,
          "exclusiveMinimum": true
        }
      }
    },
    "v1Sheet": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "sh_buyers",
          "description": "Stable Sheet identifier."
        },
        "name": {
          "type": "string",
          "example": "AI infrastructure buyers",
          "description": "Sheet display name."
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "v1SignalAgent": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "ag_discovery",
          "description": "Stable identifier of a non-archived Signal Agent configured in the portal."
        },
        "status": {
          "type": "string",
          "example": "active",
          "enum": [
            "active",
            "paused"
          ],
          "description": "Whether this agent has an enabled recurring schedule. Active does not mean a run is currently executing."
        },
        "schedule": {
          "type": "string",
          "example": "4x daily",
          "description": "Human-readable schedule label such as daily, 4x daily, or manual. This is a display string rather than a cron expression."
        },
        "next_check_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-11-17T08:00:00Z",
          "description": "Next scheduled check time, or null when none is scheduled.",
          "x-nullable": true
        },
        "sheet": {
          "$ref": "#/definitions/v1Sheet",
          "description": "Sheet associated with the agent, or null when no named Sheet is available.",
          "x-nullable": true
        }
      },
      "required": [
        "id",
        "status",
        "schedule",
        "next_check_at",
        "sheet"
      ]
    },
    "v1SignalHistoryEntry": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "sig_finding",
          "description": "Stable identifier of the saved material finding. Use this ID to identify the same finding inside an evaluation."
        },
        "type": {
          "type": "string",
          "example": "topic_engagement_signal",
          "description": "Stable signal source ID. Current types and additional historical source IDs are described in Signal Types."
        },
        "name": {
          "type": "string",
          "example": "Post Engagers",
          "description": "Human-readable signal name following portal labels."
        },
        "summary": {
          "type": "string",
          "example": "Engaged with relevant topic content.",
          "description": "Summary recorded for this exact finding; empty string when unavailable."
        },
        "reason": {
          "type": "string",
          "example": "Engagement matches the configured topic.",
          "description": "Explanation recorded for this exact finding; empty string when unavailable."
        },
        "found_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-08-10T08:00:00Z",
          "description": "When this finding was first saved in Plyne. Used for history ordering and date filtering."
        },
        "observed_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-08-09T12:00:00Z",
          "description": "Observation timestamp from source evidence, or null when unavailable. It can differ from found_at, particularly for older findings.",
          "x-nullable": true
        },
        "source_sheet": {
          "$ref": "#/definitions/v1Sheet",
          "description": "Sheet that produced this finding, or null when it has no source Sheet.",
          "x-nullable": true
        },
        "signal_agent_id": {
          "type": "string",
          "example": "ag_discovery",
          "description": "Signal Agent that produced the finding. Empty string when no Signal Agent is associated with the finding."
        },
        "qualification": {
          "$ref": "#/definitions/v1Qualification",
          "description": "Qualification recorded for this finding, or null. Historical unqualified and unclear decisions remain readable.",
          "x-nullable": true
        },
        "ai_score": {
          "$ref": "#/definitions/v1Score",
          "description": "AI score recorded for this finding, or null when uncalculated. It is not replaced by the entity current score.",
          "x-nullable": true
        },
        "references": {
          "type": "array",
          "example": [],
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1Reference"
          },
          "description": "Available source links for this finding, deduplicated by URL and limited to at most 20. Empty array when no links are available.",
          "maxItems": 20
        }
      },
      "required": [
        "id",
        "type",
        "name",
        "summary",
        "reason",
        "found_at",
        "observed_at",
        "source_sheet",
        "signal_agent_id",
        "qualification",
        "ai_score",
        "references"
      ]
    },
    "v1SignalSource": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Stable signal source type ID."
        },
        "name": {
          "type": "string",
          "description": "Signal display name used by the portal."
        },
        "source_sheet": {
          "$ref": "#/definitions/v1Sheet",
          "description": "Source Sheet for this configured source, or null.",
          "x-nullable": true
        },
        "signal_agent_id": {
          "type": "string",
          "description": "Signal Agent identity associated with this source, or an empty string."
        },
        "finding_id": {
          "type": "string",
          "description": "Representative finding ID for this source identity. It is not guaranteed to be the newest finding."
        },
        "is_primary": {
          "type": "boolean",
          "description": "Whether this is the source shown first on the selected portal row. Other sources appear in the portal's additional-source stack."
        }
      },
      "required": [
        "type",
        "name",
        "source_sheet",
        "signal_agent_id",
        "finding_id",
        "is_primary"
      ]
    },
    "v1Sort": {
      "type": "object",
      "properties": {
        "field": {
          "type": "string",
          "example": "found_at",
          "enum": [
            "",
            "found_at",
            "latest_signal_at",
            "ai_score",
            "signal_count"
          ],
          "default": "found_at",
          "description": "Sort field. Empty or omitted uses found_at."
        },
        "direction": {
          "type": "string",
          "example": "desc",
          "enum": [
            "",
            "asc",
            "desc"
          ],
          "default": "desc",
          "description": "Sort direction. Empty or omitted uses desc."
        }
      }
    },
    "v1TimeRange": {
      "type": "object",
      "properties": {
        "start_time": {
          "type": "string",
          "format": "date-time",
          "example": "2026-11-01T00:00:00Z",
          "description": "Inclusive lower timestamp bound. Either bound may be omitted; start_time must be earlier than end_time when both are supplied."
        },
        "end_time": {
          "type": "string",
          "format": "date-time",
          "example": "2026-12-01T00:00:00Z",
          "description": "Exclusive upper timestamp bound. Either bound may be omitted; start_time must be earlier than end_time when both are supplied."
        }
      }
    }
  },
  "securityDefinitions": {
    "BearerAuth": {
      "type": "apiKey",
      "description": "Organization-scoped API key. Send the complete value: Bearer plyne_...",
      "name": "Authorization",
      "in": "header"
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}
