For developers

UCP + ACP API, npm package & TypeScript SDK

Run the same 4-level UCP validation and ACP readiness checks from your own code — not just from the website. Call the public REST API from any language (no API key), or drop the @ucptools/validator npm package into your Node project for typed, in-process validation.

npm + TypeScript REST API Response shape FAQ

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 (rate-limited) — 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

Method	Endpoint	What it does
POST	`/api/validate`	AI readiness score (0-100) + grade (A-F) for a domain
POST	`/api/acp-check`	Agentic Commerce Protocol (ACP) readiness report
POST	`/api/v1/profiles/validate-remote`	4-level UCP validation of a live domain
POST	`/api/v1/profiles/validate`	Validate a UCP profile object
POST	`/api/v1/profiles/validate-quick`	Structure-only fast validation
POST	`/api/v1/profiles/validate-json`	Validate a raw JSON profile string

Generation

Method	Endpoint	What it does
POST	`/api/v1/profiles/generate`	Build a full UCP Business Profile
POST	`/api/v1/profiles/generate-minimal`	Checkout-only minimal profile
POST	`/api/generate-schema`	Generate Schema.org structured data
POST	`/api/generate-compliance`	Generate agent-data compliance documents
POST	`/api/v1/hosting/artifacts`	Deploy configs (Nginx, Vercel, Netlify, Cloudflare, S3)

Analysis & simulation

Method	Endpoint	What it does
POST	`/api/analyze-feed`	Product feed quality analysis
POST	`/api/security-scan`	Endpoint security scan
POST	`/api/simulate`	Simulate an AI agent interaction (discovery + checkout)
POST	`/api/benchmark`	Benchmark a domain against the directory

Directory & badges

Method	Endpoint	What it does
GET	`/api/directory`	List merchants in the public UCP directory
GET	`/api/directory-stats`	Aggregate directory statistics
GET	`/api/v1/tiers`	Available plan tiers and limits
GET	`/api/badge/{domain}.svg`	UCP-verified badge SVG for a domain

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.

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 }
}

FAQ

Do I need an API key?

No. The public validation, generation, and analysis endpoints under https://ucptools.dev/api are unauthenticated and rate-limited — the same endpoints the website and the GitHub Action call. Just POST a domain and read the JSON back.

What is the difference between the npm package and the REST API?

Same validation engine, two entry points. The @ucptools/validator npm package runs the 4-level validation locally in your Node process (offline for profile-object checks, with TypeScript types), and also gives you the ucp-validate CLI. The REST API runs it as a hosted service you can call from any language over HTTPS. Use the package when you want it in your build; use the API when you want a language-agnostic call.

Is the package typed?

@ucptools/validator ships its own TypeScript declarations (dist/index.d.ts). Every exported function — validateRemote, validateProfile, buildProfile, scanEndpointSecurity, analyzeProductFeed and more — plus the ValidationReport / ValidationIssue shapes are fully typed, so your editor autocompletes issue codes and severities.

Can I run this in CI/CD?

Yes — that is the most common use. The published GitHub Action gates builds on a readiness grade or score, and the CLI exits non-zero on a failing profile so it fails any job. See the CI/CD recipes page for GitHub Actions, GitLab, and CircleCI copy-paste configs.

Try it on a real domain

Run a free readiness check in the browser, or wire the API and CLI into your own pipeline.

Check any domain free →CI/CD recipes →