# public-api

Clay Public API — HTTP access for building services, apps, and integrations: GTM database search, structured table queries, and async routine and batch runs.

Skill by Clay. Category: Knowledge.

## Install

Project (for this project only):

```sh
npx skills add clay-run/agent-plugins --skill public-api
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add clay-run/agent-plugins --skill public-api -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 1. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/clay-run/agent-plugins/public-api)

## Source

[Open the source](https://github.com/clay-run/agent-plugins/tree/HEAD/clay/skills/public-api). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: public-api
description: 'Clay Public API — HTTP access for building services, apps, and integrations: GTM database search, structured table queries, and async routine and batch runs.'
---

# The Clay Public API

Beyond the CLI, Clay exposes a Public API you can develop against directly over HTTP.
Reach for it when building a service, app, or integration — not for one-off agent tasks
in a shell (use the `cli` skill for those).

## What it offers

- **Search** — find people or companies in Clay's GTM database.
  - **Advanced queries (beta)** are the default and support filters-mode criteria, cross-entity filters, and nested Boolean logic.
  - Use **structured filters** (filters mode) if the user prefers its older structure or has existing filters-mode searches.
    See the `search` skill for search behavior and the CLI equivalent. Prefer the CLI for one-off searches.
- **Tables** — structured queries against Clay tables.
- **Routines / batches** — async routine and batch runs.

## Auth

The public API needs its **own** key — the credential from `clay login` is **not**
scoped for it. Issue a dedicated public-API key with the CLI:

```bash
clay api-keys create --name "<name>"   # → { ..., "apiKey": "<secret>" }
```

CLI-created keys are always scoped to the public API. The `apiKey` secret is returned
**only once**, at creation — store it immediately; it can't be retrieved later. Send it
as a Bearer token against `https://api.clay.com/public/v0`. Manage existing keys with
`clay api-keys list | update | delete`.

## Reference

Full developer documentation — Public API reference, CLI reference, concepts, and the
OpenAPI spec — lives at:

- <https://developers.clay.com/llms.txt>

Fetch that first to get exact endpoints, request/response shapes, pagination, and rate
limits before writing integration code.
````

- Previous: [onboard](https://syn4pse.dev/terminal/clay-onboard.md)
- Next: [tables-analyze](https://syn4pse.dev/terminal/clay-tables-analyze.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
