# Playbooks integration kit

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

Canonical guide: <https://engine.neraperla.com/docs/integration-kit>

Raw Markdown: <https://engine.neraperla.com/docs/raw/integration-kit.md>

OpenAPI: <https://engine.neraperla.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://engine.neraperla.com/docs/integration-kit/reference-app/src/index.ts), [package file](https://engine.neraperla.com/docs/integration-kit/reference-app/package.json), [lockfile](https://engine.neraperla.com/docs/integration-kit/reference-app/package-lock.json), and [TypeScript configuration](https://engine.neraperla.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://engine.neraperla.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 sends no `Blackpearl-Project` header, so give it a 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://engine.neraperla.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 and query parameter, `Idempotency-Key` and `X-Request-ID` header, JSON request example, and documented success status. It does not add the `Blackpearl-Project` header: use a project key as `apiKey`, or, with a company-level key, add `Blackpearl-Project` with the project's id or slug yourself (see [Authentication](https://engine.neraperla.com/docs/authentication)). 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://engine.neraperla.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.
