Clay package v2.0.0

A Clay Public API key, held in the client's own secret manager. The stored material must be the complete clay-api-key header value: the bare key with no scheme prefix, as Clay's own examples send it. customer_vault is the only generally-supported production custody model here — identity_federation and customer_broker are refused at startup and inline is lab-only.

Issuance, per Clay's quickstart: a key is created in the Clay app under Settings > Account > API keys (currently labeled beta), or generated by the agent plugin after install. Scope model: Clay documents keys as tied to a specific Clay user and inheriting that user's workspace access — a key is not a service account, so it can reach exactly what its creating user can reach, and it stops working if that user is removed from the workspace; mint the key from a user whose workspace membership is limited to what this integration needs, monitor for 401s, and tie key rotation to the offboarding process, because there is no org-scoped alternative today.

Least privilege: the key inherits the user's workspace access wholesale (no per-endpoint scoping is documented), so least privilege is exercised through the choice of the issuing user, and through the deployment's own spend ceiling — Clay documents credit budgets only for MCP users, not for Public API keys.

Expiry and revocation: the retrieved first-party pages document creation but not scheduled expiry, rotation semantics or a revocation API (the dedicated authentication page at developers.clay.com/public-api/authentication was retrieved and likewise documents none); treat keys as long-lived until deleted in Clay settings, own rotation and revocation as external administrative actions, and ensure a stale value fails closed. The executor injects the stored value verbatim and performs no credential lifecycle itself.

Executor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack.

The endpoint host 'clay-public-api.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD, a deliberate fail-closed default): substitute the real host before enabling, in the endpoints, the resource locators and the egress allowlist — the allowlist matches exactly, so all three must be substituted together, and substitution is a required deployment step. The real host is api.clay.com and every registered path sits under the /public/v0 base path of Clay's Public API, the developer platform Clay launched on 9 July 2026.

This pack registers only operations documented in Clay's official developer documentation at developers.clay.com, retrieved on the review date: the search query-language reference read, advanced-search create and run, routine run start, routine run results read, and the table query. Searches are POST-with-query-body shapes whose documented effect is retrieval: creating a search posts a query in Clay's documented query language and returns a search_id (no records change hands), and running a search is a stateful iterator that pages records until has_more is false — the run is registered read at R0, while the create is registered create at R2 because it persists a separately addressable search definition even though no records change hands.

Searches are plan-capped metered reads: Clay documents per-request, per-search and per-period result limits by plan, and returns HTTP 402 (naming the limit hit) when the search quota is exhausted — 402 means out of budget, not slow-down-and-retry; malformed input returns 400. Routine execution is registered execute at R2 because a run consumes paid capacity: Clay documents that API and CLI work consumes the same Data Credits (purchased data) and Actions (operations) as equivalent in-product runs, so every run spends the workspace's paid balance; Clay documents no per-key credit budget on the Public API path (budgets exist only on the MCP surface), so the deployment must impose its own spend ceiling.

Runs are asynchronous: the run call returns a routine_run_id and results are polled from the results endpoint. Routine ids for custom functions use the documented format function:t_... — ROUTINE_ID and ROUTINE_RUN_ID are placeholders the deployment binds before enabling. Inline runs accept 1 to 100 items; the batch run surface (presigned upload URL plus run-batch start) is not registered by this pack. Workflows are documented as Alpha; this pack registers function routines only.

The table query is documented Enterprise-only and read-only: there is no list-tables endpoint, so the integration must already know its table ids (found in the Clay app URL after /tables/), and the table id travels in the request body, not the path.

Excluded operations: table writes of any kind (Clay documents the Tables primitive as read-only — no create-table, add-field or write-record operations), the older filters-mode search, batch routine runs, webhook management (run-completion webhooks are created with the clay CLI and verified with X-Clay-Signature), the Audiences and Signals primitives, the MCP surfaces (the hosted MCP connector and the local stdio MCP server that ships with the agent plugin) and the clay CLI itself — those are local or OAuth-gated surfaces outside this pack's HTTP connector — and the in-table HTTP API enrichment column, which is outbound from Clay, not an endpoint a caller invokes.

People search results and routine/table outputs conventionally contain prospect names, titles, employers and locations — personal data, classified as pii (personal data). Documentation review is complete. Deployment requirements remain: the first-party developer documentation was retrieved for this review, including the authentication page at developers.clay.com/public-api/authentication, and neither it nor the other retrieved pages document key expiry, scheduled rotation or a revocation API — those custody properties are unresolved vendor-side (see the credential note).

Versioning: every capability carries version 2.0.0, the pack version in which it was registered when the pack was rewritten against Clay's July 2026 Public API; a capability's version is the pack version in which its registration last changed.