Generate SDKs and client code from OpenAPI

Bluestone PIM publishes machine-readable OpenAPI specs for each API component. You can use these specs with OpenAPI Generator to generate an SDK or typed API client for your own integration code.

The generated clients are not official Bluestone-maintained SDK packages. Treat generated code as integration-owned code: review it, commit it to your project or build artifact, and regenerate it when the OpenAPI spec changes.

Machine-readable OpenAPI specs, language examples, and a test environment are available.

Environments

Choose the environment before generating or running client code.

See Environments for API and auth base URLs.

Use the test environment before running a generated client against production data.

OpenAPI specs

Each component spec is available as JSON and can be used directly with OpenAPI Generator.

Generated request examples

The API reference includes generated request examples in Shell, Node, Ruby, PHP, and Python where available. Open an endpoint in the API Reference and select the language tab for a ready-to-adapt request example.

Use those examples together with the OpenAPI specs when validating generated client behavior, authentication, headers, and request payloads.

Example API calls

These two examples show complete requests and trimmed responses you can run before or after generating a client. Set BLUESTONE_API_BASE and BLUESTONE_AUTH_BASE from the Environments page.

Get a bearer token

The Management API uses OAuth2 client-credentials bearer tokens. Exchange your client ID and secret for an access token at the authentication URL (Generate token).

curl -X POST "$BLUESTONE_AUTH_BASE" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

import requests

BLUESTONE_AUTH_BASE = "https://idp.test.bluestonepim.com/op/token"

response = requests.post(
    BLUESTONE_AUTH_BASE,
    headers={"Content-Type": "application/x-www-form-urlencoded"},
    data={
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
    },
    timeout=20,
)
response.raise_for_status()
access_token = response.json()["access_token"]

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

List products with cursor pagination

Read product pages with Get products using cursor with details from given views. Send count (1-100), an optional cursor from the previous page, and the views you want. Repeat with the returned nextCursor until it is absent.

curl -X POST "$BLUESTONE_API_BASE/pim/products/cursor/views/all" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"count": 50, "views": [{"type": "METADATA"}]}'

import requests

BLUESTONE_API_BASE = "https://api.test.bluestonepim.com"

response = requests.post(
    f"{BLUESTONE_API_BASE}/pim/products/cursor/views/all",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={"count": 50, "views": [{"type": "METADATA"}]},
    timeout=20,
)
response.raise_for_status()
page = response.json()
products = page["data"]
next_cursor = page.get("nextCursor")  # pass back as "cursor" for the next page

Response (trimmed):

{
  "data": [
    {
      "id": "01HXYZ...",
      "metadata": {
        "number": "SKU-1001",
        "type": "SINGLE",
        "lastUpdate": 1716960000000
      }
    }
  ],
  "nextCursor": "eyJsYXN0SWQiOiIwMUhYWVoi..."
}

Generate client code

The examples below use openapi-generator through npx, so they can run without a global install. Replace the input path with any component spec from the table above. Set SPEC_BASE for your environment from the Environments page.

Python

# Set SPEC_BASE from the Environments page.
npx @openapitools/openapi-generator-cli generate \
  -i $SPEC_BASE/openapi/pim.json \
  -g python \
  -o ./generated/bluestone-pim-python \
  --additional-properties=packageName=bluestone_pim_client

TypeScript/Node

# Set SPEC_BASE from the Environments page.
npx @openapitools/openapi-generator-cli generate \
  -i $SPEC_BASE/openapi/pim.json \
  -g typescript-axios \
  -o ./generated/bluestone-pim-typescript \
  --additional-properties=npmName=@your-org/bluestone-pim-client,supportsES6=true

Java

# Set SPEC_BASE from the Environments page.
npx @openapitools/openapi-generator-cli generate \
  -i $SPEC_BASE/openapi/pim.json \
  -g java \
  -o ./generated/bluestone-pim-java \
  --additional-properties=groupId=com.yourorg,artifactId=bluestone-pim-client,library=okhttp-gson

C#

# Set SPEC_BASE from the Environments page.
npx @openapitools/openapi-generator-cli generate \
  -i $SPEC_BASE/openapi/pim.json \
  -g csharp \
  -o ./generated/bluestone-pim-csharp \
  --additional-properties=packageName=BluestonePim.Client,targetFramework=net8.0

Configure authentication

Bluestone PIM Management API uses OAuth2 bearer tokens. Generate a token with the authentication URL for your environment, then pass the access token as a bearer token in API requests.

Generated SDKs usually expose either a bearer token configuration value or a request interceptor. Set the token before making API calls, and refresh it when it expires.

Validate generated clients

After generating client code:

1. Run the generated client tests, if the generator created any.
2. Point the client at the test environment.
3. Generate a bearer token with test credentials.
4. Call a read-only endpoint first, such as a list or get endpoint.
5. Compare the generated request with the Shell, Node, Ruby, PHP, or Python example in the API Reference.

For AI agents

The Bluestone PIM API exposes machine-readable OpenAPI specs for all documented components. AI agents can discover the specs from this page or the OpenAPI documentation page, then use openapi-generator examples for Python, Node, Java, and C# client generation.

An LLM index is also available at /llms.txt. The LLM index provides AI-readable documentation links and endpoint information so agents can find OpenAPI specs, API reference pages, language examples, authentication guidance, and test environment details.

Recommended agent workflow:

1. Read /llms.txt to discover documentation and reference pages.
2. Select the relevant OpenAPI component spec.
3. Generate an SDK or typed client with openapi-generator.
4. Authenticate with OAuth2 in the test environment.
5. Validate generated calls against the API Reference language examples before using production credentials.