HTTP SDKs

Typed HTTP clients for the Polycrate API in Go, Python and JavaScript/TypeScript: installation from GitHub, authentication with Bearer keys and minimal usage examples.

HTTP SDKs

Typed HTTP clients for the Polycrate API in Go, Python and JavaScript/TypeScript. One public GitHub repository, three languages, the same OpenAPI description.

The clients wrap HTTP. They manage neither resource lifecycle nor idempotency. The SDK version matches the API version (API 0.33.0 → tag v0.33.0). The packages are not published on PyPI or npm — install from GitHub only, and pin the tag to the API you are talking to.

Repository: github.com/ayedode/polycrate-sdk

Live OpenAPI: GET /api/v1/schema/. Interactive docs: /api/docs/.

Authentication

Protected endpoints expect:

Authorization: Bearer <token>

HTTP Basic on /api/v1/… is not sufficient. Long-lived keys are created in the web UI (the secret is shown once):

Creation, permissions and revocation: API Keys & Authentication.

Optionally, a short-lived user token:

curl -X POST https://api.acme.corp/api/login/ \
  -H "Content-Type: application/json" \
  -d '{"username":"ops@acme.corp","password":"<password>"}'

The response contains token. The same keys apply to the API MCP.

Base URL of the instance without a path suffix, e.g. https://api.acme.corp.

Go

Go 1.23+.

go get github.com/ayedode/polycrate-sdk/go@v0.33.0

package main

import (
    "context"
    "fmt"
    "net/http"
    "os"

    polycrate "github.com/ayedode/polycrate-sdk/go"
)

func main() {
    token := os.Getenv("POLYCRATE_TOKEN")
    client, err := polycrate.NewClientWithResponses("https://api.acme.corp",
        polycrate.WithRequestEditorFn(func(_ context.Context, req *http.Request) error {
            req.Header.Set("Authorization", "Bearer "+token)
            return nil
        }),
    )
    if err != nil {
        panic(err)
    }

    pageSize := 3
    resp, err := client.ApiV1WorkspacesListWithResponse(context.Background(), &polycrate.ApiV1WorkspacesListParams{
        PageSize: &pageSize,
    })
    if err != nil {
        panic(err)
    }
    if resp.JSON200 == nil {
        panic(fmt.Sprintf("HTTP %d", resp.StatusCode()))
    }
    fmt.Println(resp.JSON200.Count)
}

Every OpenAPI operation becomes a method on Client / ClientWithResponses (e.g. ApiV1WorkspacesListWithResponse). Successful JSON is available on JSON200 (or the matching status field). List names such as WorkspaceList.Name are pointers.

Python

Python 3.11+, dependencies httpx and attrs.

pip install "polycrate @ git+https://github.com/ayedode/polycrate-sdk.git@v0.33.0#subdirectory=python/polycrate"

from polycrate import AuthenticatedClient
from polycrate.api.api.api_v1_workspaces_list import sync_detailed

client = AuthenticatedClient(
    base_url="https://api.acme.corp",
    token="...",
    prefix="Bearer",
)

resp = sync_detailed(client=client, page_size=3)
if resp.status_code != 200 or resp.parsed is None:
    raise SystemExit(f"HTTP {resp.status_code}")
print(resp.parsed.count, [ws.name for ws in resp.parsed.results])

Every path becomes a module under polycrate.api.api with four calls:

• sync / sync_detailed — blocking
• asyncio / asyncio_detailed — async

*_detailed always returns a Response (status_code, content, parsed). Token auth via AuthenticatedClient, public endpoints via Client.

Locally from a clone: pip install ./python/polycrate.

JavaScript / TypeScript

ESM. The package ships TypeScript sources (js/src), no separate build.

npm i github:ayedode/polycrate-sdk#v0.33.0:js

import { OpenAPI, apiV1WorkspacesList } from "@ayedo/polycrate-sdk";

OpenAPI.BASE = "https://api.acme.corp";
OpenAPI.TOKEN = process.env.POLYCRATE_TOKEN;

const page = await apiV1WorkspacesList({ pageSize: 3 });
console.log(page.count, page.results.map((ws) => ws.name));

Set OpenAPI.TOKEN once — the client sends Authorization: Bearer. Every operation is a named function (apiV1WorkspacesList, apiV1OrganizationsList, …). Query fields are camelCase (pageSize).

Locally from a clone: npm i ./js.

Support

The repository is generated. Pull requests and GitHub issues are not accepted.

Send problems (language, version, minimal request) to support@ayedo.de. Do not include tokens, passwords or customer data.

License: Apache 2.0.

Further reading

• API Keys & Authentication
• MCP (Platform)
• Polycrate API — Overview
• github.com/ayedode/polycrate-sdk