# SDKs

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](/docs/reference/overview) if `playbooks-sdk` is unavailable.

A TypeScript read using a synthetic Workspace identifier:

```ts
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:

```python
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](/docs/reference/authentication) with the needed permissions. Do not put one in browser code.

## Choose the next reference

Use the [API reference](/docs/reference/overview) 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](/docs/cli/overview) and [MCP](/docs/mcp/overview).

## 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](/docs/reference/pagination) to continue lists and [Errors](/docs/reference/errors) to distinguish authentication, permission, funding, and input failures. Use the installed package’s interfaces for the exact method signatures.