Playbooks integration kit

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

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, package file, lockfile, and TypeScript configuration form the complete sample. Download those files into the same layout, then run:

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, 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). 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 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.