UCP + ACP API, npm package & TypeScript SDK

npm package + TypeScript SDK

@ucptools/validator is a published npm package. It gives you the ucp-validate CLI and a programmatic API with first-class TypeScript types — validation runs in your own Node process.

# Install the CLI + programmatic API (ships TypeScript types)
npm install @ucptools/validator

# Or run the CLI without installing
npx -p @ucptools/validator ucp-validate validate --remote yourstore.com

Import and validate in TypeScript

Every export is typed, including the ValidationIssue shape, so your editor autocompletes issue codes and severities:

import {
  validateRemote,      // 4-level validation of a live domain's UCP profile
  validateProfile,     // validate a profile object you already have
  buildProfile,        // generate a full UCP profile
  scanEndpointSecurity,
  analyzeProductFeed,
} from '@ucptools/validator';

// Validate a live merchant's published UCP profile
const report = await validateRemote('yourstore.com');

if (!report.ok) {
  for (const issue of report.issues) {
    // issue: { severity, code, path, message, hint? } — fully typed
    console.error(`[${issue.severity}] ${issue.code} ${issue.path}: ${issue.message}`);
  }
  process.exit(1); // gate your own pipeline
}

Gating a build instead of a script? The published GitHub Action and the CLI both fail your job on a bad profile — see the CI/CD recipes for GitHub Actions, GitLab, and CircleCI.

REST API

Base URL https://ucptools.dev/api. The validation, generation, and analysis endpoints are public and unauthenticated (burst-limited per IP - see rate limits) - POST a domain and read JSON back from any language.

Check a domain

# AI readiness score + grade for a domain (no API key)
curl -X POST https://ucptools.dev/api/validate \
  -H "Content-Type: application/json" \
  -d '{"domain":"yourstore.com"}'

# Same check over GET, handy for a quick shell one-liner
curl "https://ucptools.dev/api/validate?domain=yourstore.com"

Check ACP readiness

# Agentic Commerce Protocol (ACP) readiness for a domain
curl -X POST https://ucptools.dev/api/acp-check \
  -H "Content-Type: application/json" \
  -d '{"domain":"yourstore.com"}'

Full profile validation

# Full 4-level UCP validation of a live domain's profile
curl -X POST https://ucptools.dev/api/v1/profiles/validate-remote \
  -H "Content-Type: application/json" \
  -d '{"domain":"yourstore.com"}'

# Validate a UCP profile object you already have
curl -X POST https://ucptools.dev/api/v1/profiles/validate \
  -H "Content-Type: application/json" \
  -d '{"profile": { "ucp": { "version": "2025-01-01" } }}'

Endpoint reference

Readiness & validation

Generation

Analysis & simulation

Directory & badges

Both /api/v1/... and the canonical /api/... convenience paths resolve to the same service. The readiness endpoints accept a domain in a JSON body; /api/validate also accepts ?domain= over GET.

Rate limits & API keys

There are two separate limits, and each has its own headers.

Burst limit (everyone, per IP)

10 requests/second per IP address, with bursts of up to 20. Beyond that you get 429 Too Many Requests with a Retry-After header in seconds. This applies to anonymous and keyed calls alike.

Monthly allowance (API keys)

Send a key from your dashboard as X-API-Key on POST /v1/profiles/validate. Keyed calls count against your plan's monthly allowance. The allowance belongs to your account and is shared by all your keys. It resets at the start of each UTC month. Every keyed response carries:

• X-RateLimit-Limit - your monthly allowance
• X-RateLimit-Remaining - calls left this month
• X-RateLimit-Reset - when the counter resets (Unix epoch seconds)

Once the allowance is spent, keyed calls return 429 with callsThisMonth and monthlyLimit in the body and Retry-After set to the reset. Calls made without a key are not metered monthly.

X-RateLimit-* always means the monthly allowance. The IETF RateLimit / RateLimit-Policy headers are reserved for a future per-key burst window, so adding one will not change what these headers mean.

Response shape

Every validation response carries an issues array of the same structure — the REST API and the npm package return identical shapes, so you can prototype against one and switch to the other without changing your parsing.

{
  "ok": false,
  "issues": [
    {
      "severity": "error",           // "error" | "warn" | "info"
      "code": "UCP_MISSING_SIGNING_KEYS",
      "path": "$.ucp.capabilities[0]",
      "message": "No signing keys found — agents can't verify the manifest.",
      "hint": "Add an Ed25519 or ES256 signing key to the capability."
    }
  ]
  // /api/validate additionally returns:
  //   "ai_readiness": { "score": 0-100, "grade": "A".."F" }, "ucp": { "found": true }
}