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.

TypeScript / Node

Once published:

$
npm install @pivotal/api
$
# or
$
bun add @pivotal/api

1
import { PivotalApi } from "@pivotal/api";
2
3
const pivotal = new PivotalApi({ apiKey: process.env.PIVOTAL_API_KEY });
4
5
// Create a customer
6
const customer = await pivotal.customers.create({
7
  name: "Aurora Outfitters",
8
  slug: "aurora",
9
  status: "onboarding",
10
});
11
12
// Walk all active onboardings
13
for await (const onb of pivotal.onboardings.list({ state: "active" })) {
14
  console.log(onb.display_id, onb.name);
15
}

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:

$
pip install pivotal
$
# or
$
uv add pivotal

1
import os
2
from pivotal import PivotalApi
3
4
pivotal = PivotalApi(api_key=os.environ["PIVOTAL_API_KEY"])
5
6
customer = pivotal.customers.create(
7
    name="Aurora Outfitters",
8
    slug="aurora",
9
    status="onboarding",
10
)
11
12
for onb in pivotal.onboardings.list(state="active"):
13
    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
• 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 operationIds — 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 with the SDK version (pivotal.__version__ / PivotalApi.VERSION), the method you called, and the response you got.