Skip to content

Use @playbooks/sdk from Node.js 22.12+ or playbooks-sdk from Python 3.11+ for trusted backend and automation code. Both clients wrap supported Playbooks platform operations; the API's permissions, Workspace scope, funding, and resource roles still apply. Keep developer keys on the server.

Install and connect

Install a published version of @playbooks/sdk with npm install @playbooks/sdk. Python package publication is not yet confirmed; use the HTTP API if playbooks-sdk is unavailable.

A TypeScript read using a synthetic Workspace identifier:

import { PlaybooksSDK } from '@playbooks/sdk';
 
const client = new PlaybooksSDK({ apiKey: process.env.PLAYBOOKS_API_KEY });
const workspace = await client.workspaces.get('WORKSPACE_UUID');
const { data: projects, meta } = await workspace.projects.list({ page: 0, pageSize: 20 });
 
for (const project of projects) {
  console.log(project.uuid, project.name);
}
console.log('More results:', meta?.hasMore);

The Python client offers synchronous and asynchronous APIs. Once the package is available in your environment, the equivalent synchronous read is:

import os
from playbooks_sdk import PlaybooksSDK
 
with PlaybooksSDK(api_key=os.environ['PLAYBOOKS_API_KEY']) as client:
    workspace = client.workspaces.get('WORKSPACE_UUID')
    page = workspace.projects.list(page=0, page_size=20)
    for project in page['data']:
        print(project.uuid, project.name)

The SDK does not read your environment or CLI credentials automatically; the examples pass the key explicitly from your application. Use a developer key with the needed permissions. Do not put one in browser code.

Choose the next reference

Use the API reference for supported operations and request/response contracts. SDK methods can simplify resource traversal, but an accepted asynchronous operation may still need a later status check. For a terminal or external agent client, see CLI and MCP.

Check the first result

Replace the synthetic Workspace identifier with one your key can access. Inspect the returned list metadata rather than assuming the first response contains every Project. An empty result and a denied request are different outcomes.

Use Pagination to continue lists and Errors to distinguish authentication, permission, funding, and input failures. Use the installed package’s interfaces for the exact method signatures.