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	Installation command	Guide
Python (3.8+)	crusoe-ai-platform	pip install ./sdk/python	Python SDK guide
TypeScript / Node.js (18+)	@crusoe-ai/sdk	npm install ./sdk/typescript	TypeScript SDK guide
Go (1.20+)	github.com/crusoe/cai/sdk/go	go get github.com/crusoe/cai/sdk/go	Go SDK guide

---

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.dev

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.dev
Serverless API	CAI_SERVERLESS_API	https://api.codyhill.dev
VectorDB API	CAI_VECTORDB_API	https://api.codyhill.dev
MemoryStore API	CAI_MEMORYSTORE_API	https://api.codyhill.dev
Pub/Sub API	CAI_PUBSUB_API	https://api.codyhill.dev

---

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

Choose your programming language to view installation steps and 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.