# Playbooks integration kit

> Run the standalone reference product or import an OpenAPI-derived request collection.

Canonical guide: <https://api.blackpearl.com/docs/integration-kit>

Raw Markdown: <https://api.blackpearl.com/docs/raw/integration-kit.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

The integration kit is a complete, server-side Playbooks example plus request tooling generated from the same OpenAPI contract as the API reference. It uses only public HTTP behavior and published types; it has no dependency on gateway or console internals.

## Standalone reference product

The [reference app source](https://api.blackpearl.com/docs/integration-kit/reference-app/src/index.ts), [package file](https://api.blackpearl.com/docs/integration-kit/reference-app/package.json), [lockfile](https://api.blackpearl.com/docs/integration-kit/reference-app/package-lock.json), and [TypeScript configuration](https://api.blackpearl.com/docs/integration-kit/reference-app/tsconfig.json) form the complete sample. Download those files into the same layout, then run:

```bash
npm ci
export BLACKPEARL_API_BASE_URL="https://api.blackpearl.com"
export BLACKPEARL_API_KEY="replace-with-your-development-project-key"
npm run serve
```

Open `http://127.0.0.1:8787` after the command reports success. The browser receives rendered result text, never the project key.

The app persists its exact request, idempotency key, job ID, latest typed job, and successful result in `.blackpearl-reference/state.json`. Restarting resumes an active job or renders the stored result without creating new work. Use `npm run reset` only when you intentionally want a new job.

The implementation demonstrates:

- Bearer authentication read only from the server environment.
- An idempotency key persisted before the first POST and reused with identical input after an ambiguous transport failure.
- A job ID persisted before bounded polling, with restart-safe resume.
- Two-second initial polling and exponential backoff with jitter capped at ten seconds.
- Separate handling for transient `rate_limit_exceeded`, non-retryable `quota_exceeded` and `budget_exceeded`, authentication errors, failed/canceled jobs, and `410 job_expired`.
- Runtime validation before rendering `business_summary`, `sales_angles`, and `value_props`; generated text is HTML-escaped.

The same `run` command targets any gateway whose Playbooks backend is configured, including an isolated local service or a hosted development project. Calls perform real capability work and record real usage; an unconfigured backend fails closed.

## Postman collection

Download the [Blackpearl Public API Postman collection](https://api.blackpearl.com/docs/integration-kit/blackpearl-public-api.postman_collection.json), import it, and set its `baseUrl` and `apiKey` collection variables. Set `idempotencyKey` to a unique retained value before a job-creation request. If a create response is ambiguous, resend the unchanged request with that same value.

The collection contains every current public OpenAPI operation, HTTP method, path/query/header parameter, JSON request example, and documented success status. Its metadata records the exact OpenAPI document version and SHA-256 digest. `make integration-kit-check` regenerates it in memory and fails on contract drift.

## Client support policy

The [Python and TypeScript quickstarts](https://api.blackpearl.com/docs/getting-started#python-and-typescript-versions) and this product are deliberately dependency-light reference clients, not supported SDK packages. Broad official SDK generation remains deferred until API stability and adoption justify the compatibility and release burden. Their automated tests use explicit test-only HTTP fixtures; the shipped clients contain no simulation path.