SDKs overview

Crusoe AI Platform provides official SDKs for Python, TypeScript / Node.js, and Go. Use these libraries to integrate platform services—Agents, VectorDB, Functions, Secrets, MemoryStore, and Pub/Sub—directly into your applications.

Instead of writing raw HTTP calls, the SDKs handle request signing, JSON serialization, response parsing, error handling, and connection reuse for you.

---

Supported SDKs

Language / Runtime	Package name	Install	Guide
Python (3.8+)	crusoe-ai-platform 0.1.0	Install an SDK	Python SDK guide
TypeScript / Node.js (18+)	@crusoe-ai/platform 0.1.0	Install an SDK	TypeScript SDK guide
Go (1.18+)	www.codyhill.net/sdk/go/platform v0.1.0	Install an SDK	Go SDK guide

These packages are not on any public registry

During the private beta all three are served only from your own platform's www host, beside the CLI downloads, with a checksum you verify before installing. There is no public repository, no PyPI release, no npm release, and nothing on proxy.golang.org. A package appearing under one of these names on a public index is not ours — see Install an SDK for the commands and the reasoning.

---

Authentication

Every API call made by an SDK requires a bearer credential. Obtain an API key or bearer token using platformctl login or from the web console.

Setting credentials

Set your API token using environment variables or directly inside SDK client configurations:

# Recommended: set via environment variable
export CAI_API_KEY="cai_pk_live_1234567890abcdef"
export CAI_PROJECT="0191f2c4-7777-7c3d-8e4f-5a6b7c8d9e0f"

In code, the SDKs automatically read CAI_API_KEY or CAI_TOKEN when no explicit token is passed during client initialization.

---

Base URLs

All services run on one public endpoint by default:

https://api.codyhill.net

You can override base URLs per service by setting environment variables in your environment:

Service	Environment variable	Default base URL
Core API (Agents, Functions, Secrets)	CAI_API	https://api.codyhill.net
Serverless API	CAI_SERVERLESS_API	https://api.codyhill.net
VectorDB API	CAI_VECTORDB_API	https://api.codyhill.net
MemoryStore API	CAI_MEMORYSTORE_API	https://api.codyhill.net
Pub/Sub API	CAI_PUBSUB_API	https://api.codyhill.net

---

Core usage patterns

1. Unified error envelope

All non-2xx responses from platform endpoints return a standard JSON error structure:

{
  "error": "resource not found or access denied",
  "request_id": "req_01J8F9X2K3P4Q5R6S7T8"
}

Every SDK parses this payload and raises a typed exception or error object containing both the human-readable error message and the request_id for tracing.

2. The 404 security rule

To prevent unauthorized users from enumerating project names or resource IDs, requests against resources outside your access grant return 404 Not Found rather than 403 Forbidden. You only receive 403 Forbidden if you hold a project grant but lack the specific permission for an action (such as revealing a secret or deleting a production agent).

3. Pagination conventions

List endpoints use cursor-based pagination. Pass page_size (1 to 200) and page_token to step through results. Response objects contain next_page_token until you reach the final page.

---

Next steps

• Install an SDK — the download-and-verify commands for all three languages. Start here; the per-language guides below assume the package is already installed.

Then choose your programming language for complete code examples:

• Python SDK guide — Complete examples for Agents, VectorDB, Functions, Secrets, MemoryStore, and Pub/Sub.
• TypeScript SDK guide — Modern async/await code examples for Node.js and TypeScript environments.
• Go SDK guide — Idiomatic Go package examples using context.Context and standard error handling.