Developers/SDK/Custom / Per-Domain SDK

Custom / Per-Domain SDK

Generate a typed Python or JavaScript client library from your own domain's schemas, and manage its versions through the SDK Generation API.

Overview

The base Python and JavaScript SDKs (see the Python SDK and JavaScript SDK pages) work against any domain out of the box using org.crud / client CRUD calls. The SDK Generation API goes one step further: it builds a client library baked with your domain's current schemas, so record fields are documented in a Python wheel or JavaScript package instead of being discovered at runtime. This page covers triggering a build, checking status, listing and downloading built SDKs, and how versioning works.

This is a per-domain, per-language build system, not a separate product: everything below is authenticated the same way as the rest of the REST API, and the generated Python artifact is still the same supero package, now pinned to a build stamped with your schemas.

Endpoint	Purpose
POST /api/v1/sdks/generate	Trigger a build for one or more languages
GET /api/v1/sdks/status/{request_id}	Poll a build you just triggered
GET /api/v1/domains/{domain_name}/sdks	List previously built SDKs
GET /api/v1/sdks/{sdk_uuid}	Get details for one built SDK
GET /api/v1/sdks/{sdk_uuid}/download	Download a build artifact
DELETE /api/v1/sdks/{sdk_uuid}	Delete a built SDK and its artifacts
GET /api/v1/domains/{domain_name}/sdks/history	Version history per language
GET /api/v1/sdks/base-version	Public — base supero package version this platform builds against

Authentication & Permissions

Every endpoint on this page except GET /api/v1/sdks/base-version requires the same auth as the rest of the API: a Bearer JWT from a logged-in user, or an API key sent as X-API-Key. The caller's domain is taken from the authenticated context — you cannot build or read another domain's SDKs.

Action	Permission required
Generate or delete an SDK	schema:manage
Check status, list, view details, download, view history	schema:read

ℹ️ Base version is public

GET /api/v1/sdks/base-version does not require authentication. It returns the base supero package name, version, and compatibility spec that generated SDKs are pinned against — useful for verifying a build matches the platform you're targeting before you generate one.

Generating an SDK

POST /api/v1/sdks/generate builds a client for every active schema in your domain. If you omit domain_name, it's taken from your authenticated context.

Field	Type	Default	Notes
domain_name	string	your authenticated domain	Must match the caller's domain
languages	array of string	["python", "javascript"]	Python and JavaScript are the only languages that build. Other values (java, go, cpp, typescript, csharp) are accepted without error, but produce no artifact — see the note below the table
force_rebuild	boolean	false	Skip the schema-hash cache and rebuild even if nothing changed
include_docs	boolean	true	Include generated reference docs as a downloadable artifact
include_tests	boolean	true	Include generated smoke tests as a downloadable artifact
python_version	string	"3.8"	Target Python version for the Python build
callback_url	string	none	Optional webhook to notify when the build completes

⚠️ Only Python and JavaScript are built

A request naming any other language is accepted rather than rejected: you get the same 202 queued response, and the build silently falls back to Python and JavaScript. Nothing in the response marks the language as unavailable, so a request for {"languages": ["java"]} looks successful and yields a Python and a JavaScript artifact. Read the languages array on the status and download responses to see what was actually built, and treat any language other than python or javascript as unavailable today.

bash

curl -X POST https://api.supero.dev/api/v1/sdks/generate \
  -H "X-API-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain_name": "acme-corp",
    "languages": ["python", "javascript"],
    "include_docs": true
  }'

The response status tells you what happened:

HTTP status	status field	Meaning
200	completed (cached: true)	Schemas haven't changed since the last build — the existing SDK(s) are returned immediately, no rebuild
202	queued	A new build was queued; poll request_id with the status endpoint
202	queued (already_building: true)	A build for this domain+language combination is already running; you were handed the in-flight request_id instead of starting a duplicate
429	cooldown	Another build for this domain+language finished too recently; retry after retry_after_seconds (the Retry-After header is also set)
500	failed	The build request could not be created — see the error field

json

// 202 — new build queued
{
  "request_id": "9f6e0c1a-...",
  "build_request_uuid": "b4a2...",
  "domain_name": "acme-corp",
  "status": "queued",
  "languages": ["python", "javascript"],
  "new_version": "1.3.0",
  "change_type": "minor",
  "estimated_time_seconds": 240,
  "poll_url": "/api/v1/sdks/status/9f6e0c1a-..."
}

json

// 200 — cache hit, no rebuild needed
{
  "request_id": "9f6e0c1a-...",
  "status": "completed",
  "cached": true,
  "sdk_uuids": ["a1b2c3d4-..."],
  "sdks": [ { "sdk_uuid": "a1b2c3d4-...", "sdk_language": "python", "sdk_version": "1.2.4", "build_status": "completed" } ]
}

Checking Build Status

A queued build runs in the background. Poll its status with the request_id from the generate response:

bash

curl https://api.supero.dev/api/v1/sdks/status/9f6e0c1a-... \
  -H "X-API-Key: ak_..."

json

{
  "request_id": "9f6e0c1a-...",
  "status": "building",
  "progress_percentage": 60,
  "current_step": "packaging",
  "generated_sdk_uuids": [],
  "error_details": null
}

status moves through pending → building → completed (or failed). Once completed, generated_sdk_uuids lists the built SDK(s) and the response includes an sdks array with per-language uuid, version, and download_url.

Listing, Inspecting, and Downloading

List every SDK built for a domain, optionally filtered by language or status:

bash

curl "https://api.supero.dev/api/v1/domains/acme-corp/sdks?language=python&limit=20" \
  -H "X-API-Key: ak_..."

Each entry includes sdk_uuid, sdk_language, sdk_version, build_status, schemas_hash, build_completed_at, and change_type. Fetch full details — including build timing and which artifacts are available — for one SDK:

bash

curl https://api.supero.dev/api/v1/sdks/a1b2c3d4-... \
  -H "X-API-Key: ak_..."

Downloading an artifact

Downloads are served directly from the API — there is no separate download host. Request the artifact you want with the artifact query parameter; the response streams the file with a Content-Disposition header set to the correct filename.

bash

curl -L "https://api.supero.dev/api/v1/sdks/a1b2c3d4-.../download?artifact=wheel" \
  -H "X-API-Key: ak_..." \
  -o acme-corp-sdk.whl

artifact value	Returns
wheel (default)	Python wheel, pinned to your domain's schemas
tarball	Python source distribution
documentation	Generated reference docs (if include_docs was set)
schemas	The schema bundle the build was generated from

ℹ️ JavaScript artifacts

For a JavaScript build, check the artifacts available on the SDK's detail response before downloading — the artifact keys returned there are what you pass in the artifact parameter.

Deleting an SDK

bash

curl -X DELETE "https://api.supero.dev/api/v1/sdks/a1b2c3d4-...?delete_artifacts=true" \
  -H "X-API-Key: ak_..."

delete_artifacts defaults to true and also removes the stored build artifacts, not just the metadata record.

Versioning & Caching

Generated SDKs are versioned with semantic versioning, but the version bump is driven by which schema types are included in the build — not by field-level changes within a schema:

What changed since the last build	Version bump
No schema types added or removed (fields may have changed)	Patch (1.2.3 → 1.2.4)
A new schema type was added to the domain	Minor (1.2.3 → 1.3.0)
A schema type was removed from the domain	Major (1.2.3 → 2.0.0)

ℹ️ Schema-hash cache

Every build is stamped with a hash of your domain's active schemas. If you call generate again with an unchanged hash and force_rebuild is not set, the platform returns the existing SDK instead of rebuilding — this is the cached: true response shown above.

⚠️ Build cooldown

There is a cooldown between builds for the same domain + language to prevent duplicate work from repeated clicks or retries. If you hit 429 with status: cooldown, wait retry_after_seconds before retrying rather than looping immediately.

Automating SDK Builds

Because the whole flow is plain REST, you can drive it from any CI system with an API key stored as a secret. This example uploads updated schemas, triggers a build, and polls until it completes:

yaml

name: Build Supero SDKs

on:
  push:
    paths:
      - "schemas/**"

jobs:
  build-sdks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Trigger SDK build
        env:
          SUPERO_API_KEY: ${{ secrets.SUPERO_API_KEY }}
        run: |
          curl -sf -X POST https://api.supero.dev/api/v1/sdks/generate \
            -H "X-API-Key: $SUPERO_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"domain_name": "acme-corp", "languages": ["python"]}' \
            | tee build_response.json

      - name: Poll for completion
        env:
          SUPERO_API_KEY: ${{ secrets.SUPERO_API_KEY }}
        run: |
          REQUEST_ID=$(jq -r '.request_id' build_response.json)
          for i in $(seq 1 30); do
            STATUS=$(curl -sf https://api.supero.dev/api/v1/sdks/status/$REQUEST_ID \
              -H "X-API-Key: $SUPERO_API_KEY" | jq -r '.status')
            echo "status: $STATUS"
            [ "$STATUS" = "completed" ] && break
            [ "$STATUS" = "failed" ] && exit 1
            sleep 10
          done

Uploading the schemas themselves before the build is a separate step — see the Schema API page for the schema upload endpoints.

Next steps

•Python SDK — installing and using the base supero package directly (org.crud, query builder, schema upload)
•JavaScript SDK — the equivalent client for Node and browser apps
•Schema API — schema field reference and the upload/update/delete endpoints a build reads from
•Authentication — JWT vs. API-key mechanics for the X-API-Key header used throughout this page

← PreviousJavaScript SDK Next →Build an App with Your Own AI Agent

On this page