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://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, 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 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.