> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-fix-release-bump-classification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Schemas and SDKs

> AdCP JSON schemas and SDKs for JavaScript, Python, and Go. Download schemas from GitHub or fetch at runtime. Includes setup for AI coding agents using Cursor, Windsurf, and Claude.

Get started integrating with AdCP using our schemas and official SDKs.

## Schema Access

AdCP schemas are available from two sources:

| Source  | URL                                                                | Best For                          |
| ------- | ------------------------------------------------------------------ | --------------------------------- |
| Website | `https://adcontextprotocol.org/schemas/3.0.19/`                    | Runtime fetching, version aliases |
| GitHub  | `https://github.com/adcontextprotocol/adcp/tree/main/dist/schemas` | Offline access, CI/CD pipelines   |

Both sources contain identical schemas. The GitHub repository includes all released versions with bundled schemas committed directly to the codebase.

### One-shot protocol bundle

Syncing hundreds of individual schema files adds up. Every AdCP release also publishes a single gzipped tarball containing the complete protocol — schemas, compliance storyboards, and the OpenAPI registry — so clients can pull one artifact instead of crawling the tree.

| Path                                                          | Contents                          | Notes                                                                                                                                                  |
| ------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `https://adcontextprotocol.org/protocol/latest.tgz`           | Current development bundle        | Changes with every merge                                                                                                                               |
| `https://adcontextprotocol.org/protocol/{version}.tgz`        | Pinned release bundle             | Immutable once published                                                                                                                               |
| `https://adcontextprotocol.org/protocol/{version}.tgz.sha256` | SHA-256 checksum                  | Use to verify download integrity                                                                                                                       |
| `https://adcontextprotocol.org/protocol/{version}.tgz.sig`    | Sigstore detached signature       | Use to verify publisher identity. Present only when the release was cut via the `release.yml` workflow — absent for out-of-band republishes.           |
| `https://adcontextprotocol.org/protocol/{version}.tgz.crt`    | Fulcio-issued signing certificate | Pairs with `.sig` for `cosign verify-blob`. Present only when the release was cut via the `release.yml` workflow — absent for out-of-band republishes. |

Every tarball extracts into a single `adcp-{version}/` directory (safe extraction, no tarbomb). Inside:

```
adcp-{version}/
  README.md               # quickstart + links
  CHANGELOG.md            # release notes
  manifest.json           # version, generated_at, contents summary
  schemas/                # full JSON schema tree (same as /schemas/{version}/)
  compliance/             # protocols/, specialisms/, universal/, test-kits/, index.json
  openapi/registry.yaml   # OpenAPI description
```

Verify the checksum before extracting:

```bash theme={null}
curl -OL https://adcontextprotocol.org/protocol/3.1.0.tgz
curl -OL https://adcontextprotocol.org/protocol/3.1.0.tgz.sha256
shasum -a 256 -c 3.1.0.tgz.sha256
tar xzf 3.1.0.tgz
cd adcp-3.1.0
```

Pull it once per version, cache by SHA, and you have everything needed to validate requests, run storyboards, and render documentation offline. The `@adcp/client` `sync-schemas` command uses this under the hood.

Available tarballs are also listed at [`/protocol/`](https://adcontextprotocol.org/protocol/).

#### Verifying protocol bundle signatures

The SHA-256 sidecar lives on the same origin as the tarball, so it only protects against in-transit tampering. For supply-chain protection — proving the bundle came from the AdCP release workflow and was not swapped for a malicious one even if the host were compromised — every released `{version}.tgz` is also published with a Sigstore detached signature.

The signature is produced by the GitHub Actions release workflow using keyless OIDC: there is no long-lived AdCP signing key to leak. The certificate binds the signature to the workflow identity that issued it.

```bash theme={null}
# Pull the tarball and the two signature sidecars
curl -OL https://adcontextprotocol.org/protocol/3.1.0.tgz
curl -OL https://adcontextprotocol.org/protocol/3.1.0.tgz.sig
curl -OL https://adcontextprotocol.org/protocol/3.1.0.tgz.crt

# Verify (requires cosign 2.x — `brew install cosign`)
cosign verify-blob \
  --signature 3.1.0.tgz.sig \
  --certificate 3.1.0.tgz.crt \
  --certificate-identity-regexp '^https://github\.com/adcontextprotocol/adcp/\.github/workflows/release\.yml@refs/heads/.*$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  3.1.0.tgz
```

`cosign verify-blob` exits non-zero if the signature was made by anything other than the AdCP release workflow, even if the SHA matches and TLS is valid. Use this in any pipeline that ingests the protocol bundle as an enforcement source. The `@adcp/client` `sync-schemas` command performs this verification automatically when the sidecars are present.

Older releases that predate signing, and versions republished out of band (bypassing the signing workflow), remain checksum-only — clients should treat missing sidecars as a "checksum-only" trust level rather than a verification failure.

### Compliance storyboards

Storyboards live alongside schemas at `/compliance/{version}/`. They define the test scenarios AAO runs to verify an agent's capability claims.

| Path                                          | Purpose                                                                                                                     |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `/compliance/{version}/universal/`            | Required for every agent (capability discovery, error handling, schema validation)                                          |
| `/compliance/{version}/protocols/{protocol}/` | Baseline required to claim a protocol (`media-buy`, `creative`, `signals`, `governance`, `brand`, `sponsored-intelligence`) |
| `/compliance/{version}/specialisms/{id}/`     | Optional specialization claims (e.g. `sales-guaranteed`, `sales-broadcast-tv`)                                              |
| `/compliance/{version}/index.json`            | Enumerates available protocols, specialisms, and universal storyboards                                                      |

Declare `supported_protocols` (for protocol baselines) and `specialisms` (for narrow capability claims) in `get_adcp_capabilities` — the compliance runner executes the matching bundles to verify. See the full [Compliance Catalog](/dist/docs/3.0.19/building/verification/compliance-catalog) for every protocol and specialism an agent can claim.

### Common Schemas

| Schema          | URL                                                                |
| --------------- | ------------------------------------------------------------------ |
| Product         | `https://adcontextprotocol.org/schemas/3.0.19/core/product.json`   |
| Media Buy       | `https://adcontextprotocol.org/schemas/3.0.19/core/media-buy.json` |
| Creative Format | `https://adcontextprotocol.org/schemas/3.0.19/core/format.json`    |
| Schema Registry | `https://adcontextprotocol.org/schemas/3.0.19/index.json`          |

### For AI Coding Agents

<Tip>
  Point your AI coding agent to **[https://docs.adcontextprotocol.org/mcp](https://docs.adcontextprotocol.org/mcp)** for MCP integration documentation.
</Tip>

## Client SDKs

AdCP provides official SDKs for JavaScript/TypeScript, Python, and Go. These work for both client and server implementations.

### AdCP 3.0 support

All three official SDKs ship AdCP 3.0. Pin to (or above) the minimum listed below and validate with the [storyboard test suite](/dist/docs/3.0.19/building/verification/validate-your-agent).

| SDK                    | 3.0-compatible from | Package                                                                                                                   |
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `@adcp/client` (JS/TS) | `5.13.0`            | [npm](https://www.npmjs.com/package/@adcp/client) · [releases](https://github.com/adcontextprotocol/adcp-client/releases) |
| `adcp` (Python)        | `4.0.0`             | [PyPI](https://pypi.org/project/adcp/) · [releases](https://github.com/adcontextprotocol/adcp-python/releases)            |
| `adcp-go` (Go)         | `v1.0.0`            | [releases](https://github.com/adcontextprotocol/adcp-go/releases)                                                         |

If you are on an earlier major version, upgrade before working through the [3.0 migration guide](/dist/docs/3.0.19/reference/migration/index).

### JavaScript / TypeScript

[![npm version](https://img.shields.io/npm/v/@adcp/client)](https://www.npmjs.com/package/@adcp/client)

```bash theme={null}
npm install @adcp/client
```

```javascript theme={null}
import { ADCPClient } from '@adcp/client';

const client = new ADCPClient({
  agentUrl: 'https://sales.example.com'
});

const products = await client.getProducts({
  brief: 'Video campaign for pet owners'
});
```

**Resources:**

* [NPM Package](https://www.npmjs.com/package/@adcp/client)
* [GitHub Repository](https://github.com/adcontextprotocol/adcp-client)

**Package exports:**

* `@adcp/client` — Main API
* `@adcp/client/testing` — Buyer-side storyboard runner (`runStoryboard`, `comply`, `testAgent`) and seller-side controller scaffold (`createComplyController` — see [Get Test-Ready](/dist/docs/3.0.19/building/verification/get-test-ready))
* `@adcp/client/server` — Low-level server helpers (MCP tool registration, state stores, `handleTestControllerRequest`)
* `@adcp/client/advanced` — Advanced API features
* `@adcp/client/types` — TypeScript type definitions

### Python

[![PyPI version](https://img.shields.io/pypi/v/adcp)](https://pypi.org/project/adcp/)

```bash theme={null}
pip install adcp
```

```python theme={null}
from adcp import ADCPClient

client = ADCPClient(agent_url='https://sales.example.com')

products = client.get_products(
    brief='Video campaign for pet owners'
)
```

**Resources:**

* [PyPI Package](https://pypi.org/project/adcp/)
* [GitHub Repository](https://github.com/adcontextprotocol/adcp-client-python)

### Go

```bash theme={null}
go get github.com/adcontextprotocol/adcp-go/adcp
```

The Go SDK provides typed tool registration, response builders, and a compliance test controller. Types are generated from canonical AdCP schemas.

| Component         | Import                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------ |
| Tool registration | `adcp.AddTool(server, name, desc, handler)`                                                                  |
| HTTP server       | `adcp.Serve(createAgent)`                                                                                    |
| Response builders | `adcp.ProductsResponse(data)`, `adcp.MediaBuyResponse(data)`, etc.                                           |
| Test controller   | `adcp.RegisterTestController(server, store)`                                                                 |
| Skills            | [github.com/adcontextprotocol/adcp-go/skills](https://github.com/adcontextprotocol/adcp-go/tree/main/skills) |

See the [Go SDK README](https://github.com/adcontextprotocol/adcp-go) for the full API reference.

**Resources:**

* [GitHub Repository](https://github.com/adcontextprotocol/adcp-go)

## CLI Tools

The JavaScript and Python SDKs include command-line tools for testing and development.

### JavaScript CLI

```bash theme={null}
npx @adcp/client@latest --help
npx @adcp/client@latest get-products --agent https://sales.example.com --brief "CTV campaign"
```

### Python CLI

```bash theme={null}
uvx adcp --help
uvx adcp get-products --agent https://sales.example.com --brief "CTV campaign"
```

## Schema Versioning

AdCP uses semantic versioning. Choose the right path for your use case:

| Path          | Example                                                        | Best For                                |
| ------------- | -------------------------------------------------------------- | --------------------------------------- |
| Exact version | `/schemas/3.0.0/`, `/compliance/3.0.0/`, `/protocol/3.0.0.tgz` | Production, SDK generation              |
| Major version | `/schemas/3.0.19/`, `/compliance/v3/`                          | Development, documentation              |
| Minor version | `/schemas/v3.0/`, `/compliance/v3.0/`                          | Stable development (patch updates only) |

The same version semantics apply to `/schemas`, `/compliance`, and `/protocol/{version}.tgz` — one release cuts all three.

### Production (Recommended)

Pin to an exact version for stability:

```javascript theme={null}
const SCHEMA_VERSION = '3.0.0';
const schema = await fetch(
  `https://adcontextprotocol.org/schemas/${SCHEMA_VERSION}/core/product.json`
);
```

### Development

Use the major version alias to stay current with backward-compatible updates:

```javascript theme={null}
const schema = await fetch(
  'https://adcontextprotocol.org/schemas/3.0.19/core/product.json'
);
```

### SDK Type Generation

```bash theme={null}
# TypeScript
npx json-schema-to-typescript \
  https://adcontextprotocol.org/schemas/3.0.0/core/product.json \
  --output types/product.d.ts

# Python
datamodel-codegen \
  --url https://adcontextprotocol.org/schemas/3.0.0/core/product.json \
  --output models/product.py
```

## Bundled Schemas

For tools that don't support `$ref` resolution, use bundled schemas with all references resolved inline. Bundled schemas are available from both the website and GitHub:

### Website Access

```
https://adcontextprotocol.org/schemas/3.0.0/bundled/media-buy/create-media-buy-request.json
```

### GitHub Access

Bundled schemas are committed to the repository at `dist/schemas/{VERSION}/bundled/`:

```bash theme={null}
# Clone and access locally
git clone https://github.com/adcontextprotocol/adcp.git
ls adcp/dist/schemas/3.0.0/bundled/media-buy/

# Or fetch directly via GitHub raw
curl https://raw.githubusercontent.com/adcontextprotocol/adcp/main/dist/schemas/3.0.0/bundled/media-buy/get-products-request.json
```

### Directory Structure

```
dist/schemas/{VERSION}/
├── bundled/                      # Fully dereferenced schemas
│   ├── media-buy/                # Media buying tasks
│   ├── creative/                 # Creative tasks
│   ├── signals/                  # Signal protocol tasks
│   ├── property/                 # Property/governance tasks
│   ├── content-standards/        # Content standards tasks
│   ├── sponsored-intelligence/   # Sponsored intelligence tasks
│   ├── protocol/                 # Protocol tasks
│   └── core/                     # Core task schemas
├── core/                         # Modular schemas with $ref
├── media-buy/
└── index.json                    # Schema registry
```

### Bundled Schema Categories

All request/response task schemas are bundled:

| Category                          | Tasks                                                                                                                                                                                                     |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bundled/media-buy/`              | get-products, create-media-buy, update-media-buy, list-creative-formats, sync-creatives, build-creative, list-creatives, get-media-buy-delivery, list-authorized-properties, provide-performance-feedback |
| `bundled/creative/`               | list-creative-formats, preview-creative                                                                                                                                                                   |
| `bundled/signals/`                | get-signals, activate-signal                                                                                                                                                                              |
| `bundled/property/`               | create-property-list, get-property-list, list-property-lists, update-property-list, delete-property-list, validate-property-delivery                                                                      |
| `bundled/content-standards/`      | create-content-standards, get-content-standards, list-content-standards, update-content-standards, calibrate-content, validate-content-delivery, get-media-buy-artifacts                                  |
| `bundled/sponsored-intelligence/` | si-get-offering, si-initiate-session, si-send-message, si-terminate-session                                                                                                                               |
| `bundled/protocol/`               | get-adcp-capabilities                                                                                                                                                                                     |
| `bundled/core/`                   | tasks-get, tasks-list                                                                                                                                                                                     |

See the [schema registry](https://adcontextprotocol.org/schemas/3.0.19/index.json) for all available schemas.

## Version Discovery

```bash theme={null}
# Get current version
curl https://adcontextprotocol.org/schemas/3.0.19/index.json | jq '.adcp_version'
```

Check [Release Notes](/dist/docs/3.0.19/reference/release-notes) for version history and migration guides.

## Registry API

The AgenticAdvertising.org registry provides a public REST API for brand resolution, property resolution, agent discovery, and authorization validation. No authentication required.

<Card title="Registry API Reference" icon="server" href="/dist/docs/3.0.19/registry/index">
  Resolve brands, discover agents, and validate authorization via REST.
</Card>