> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# SDKs

Both SDKs are generated from the same OpenAPI spec that powers this reference. Method names, parameters, and response types match the spec exactly. When the API changes additively, the next SDK release picks up the new fields without you touching anything.

Published SDK packages will land at `@pivotal/api` (npm) and `pivotal` (PyPI). Until then, generate locally with `fern generate --group local-sdks` against this repo. The hand-rolled snippets below show the shape — install steps are coming with the first published release.

## TypeScript / Node

Once published:

```bash
npm install @pivotal/api
# or
bun add @pivotal/api
```

```typescript
import { PivotalApi } from "@pivotal/api";

const pivotal = new PivotalApi({ apiKey: process.env.PIVOTAL_API_KEY });

// Create a customer
const customer = await pivotal.customers.create({
  name: "Aurora Outfitters",
  slug: "aurora",
  status: "onboarding",
});

// Walk all active onboardings
for await (const onb of pivotal.onboardings.list({ state: "active" })) {
  console.log(onb.display_id, onb.name);
}
```

Highlights:

* **`async` iterator** on every `list*` method handles cursor pagination for you. `for await` walks the full set.
* **Strict types** generated from the schema — autocomplete on request bodies, return values typed by `operationId`.
* **Configurable fetcher.** Inject your own `fetch` for retries, tracing, or test mocks.
* **Bundle size** under 30 KB minified+gzipped (rolled from spec, no runtime bloat).

## Python

Once published:

```bash
pip install pivotal
# or
uv add pivotal
```

```python
import os
from pivotal import PivotalApi

pivotal = PivotalApi(api_key=os.environ["PIVOTAL_API_KEY"])

customer = pivotal.customers.create(
    name="Aurora Outfitters",
    slug="aurora",
    status="onboarding",
)

for onb in pivotal.onboardings.list(state="active"):
    print(onb.display_id, onb.name)
```

Highlights:

* **Pydantic v2 models** for every request and response.
* **Generator-based pagination** — `list()` yields rows, walks the cursor under the hood.
* **`httpx` under the hood** with sane timeouts and connection pooling.
* **Async client** at `pivotal.AsyncPivotalApi` with the same surface.

## Other languages

The OpenAPI spec is the contract. Generate a client in your language of choice from:

```
https://my.pivotal.app/api/v1/openapi.json
```

Recommended generators:

* **Go** — [`oapi-codegen`](https://github.com/oapi-codegen/oapi-codegen)
* **Ruby** — `openapi-generator` with `ruby` target
* **C#** — `nswag` or `openapi-generator`
* **Rust** — `progenitor` or `openapi-generator`

If you generate against the spec yourself, the names of request bodies and response shapes match the `operationId`s — `createCustomer`, `listOnboardings`, etc. — so cross-referencing this site stays straightforward.

## Versioning the SDKs

SDK versions follow semver:

* **Patch** (`1.0.x`) — generator updates, bug fixes.
* **Minor** (`1.x.0`) — new endpoints, new optional fields, new enum values. Always backwards-compatible.
* **Major** (`x.0.0`) — only when the underlying API ships a `v2`.

Pin to a major version in production. Renovate / Dependabot can safely auto-bump minors.

## Reporting SDK bugs

If the SDK behaves differently than this reference says it should, that's a bug in the generator config. Email [help@pivotal.app](mailto:help@pivotal.app) with the SDK version (`pivotal.__version__` / `PivotalApi.VERSION`), the method you called, and the response you got.