TypeScript SDK
Install @hexelstudio/titan-sdk, authenticate with an access token or an API key, send the scope headers Titan reads, and handle its errors.
@hexelstudio/titan-sdk is the TypeScript client for Titan. It has typed functions for every public Titan route, React Query hooks, and flow helpers that run a whole task (create a deployment, connect an account, edit a policy) in one call.
| Import | What it has |
|---|---|
@hexelstudio/titan-sdk | The platform API: deployments, policy, tools, connections, approvals, the Agent Ledger. configure, createTransport, TitanError. |
@hexelstudio/titan-sdk/flows | Flow helpers: provisionDeployment, connectWithApiKey, startOAuth, editPolicy, allowInPolicy and the policy builders. |
@hexelstudio/titan-sdk/react | React Query v5 hooks for the platform API and the flows. |
@hexelstudio/titan-sdk/agent | The agent API, for an agent process: identity exchange, capabilities, invocations, approvals. |
Install
During the private preview, the package is published privately to GitHub Packages. Ask Hexel Studio at [email protected] for access, then point the @hexelstudio scope at GitHub Packages with a GitHub token that has the read:packages scope:
@hexelstudio:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}npm install @hexelstudio/titan-sdkThe package is ESM. The React hooks need react 18 or 19 and @tanstack/react-query 5; both are optional peer dependencies.
Base URL
Every path starts with /titan/...; the base URL carries the rest.
| Where | Base URL |
|---|---|
| Titan Cloud and management | https://api.hexelstudio.com/v1 (the default) |
| A Titan Dedicated deployment | https://api.hexelstudio.com/v1/cells/<enforcement deployment id> |
| A deployment's own hostname: everything except management | https://<enforcement deployment id>.titan.hexelstudio.com, from tenantBaseURL(id) |
A request through a deployment's own hostname acts only for that deployment. Its agent API, registry, tools and administration (approvals, the Agent Ledger, sessions) are served there, and administration calls need no Titan-Enforcement-Deployment header: the hostname names the deployment. Management (deployments, policy) is not, so keep https://api.hexelstudio.com/v1 for it.
Authenticate
The platform API takes either an access token or an API key.
Send an access token issued by https://sts.hexelstudio.com for a member or a service user of your organization (see Authenticate). Never send an ID token from your sign-in provider.
import { configure, listDeployments } from '@hexelstudio/titan-sdk';
configure({
baseURL: 'https://api.hexelstudio.com/v1',
getAccessToken: async () => (await (await fetch('/auth/sts-token', { method: 'POST' })).json()).access_token,
getContext: () => ({ organizationId, workspaceId, environmentId }),
});
const { data } = await listDeployments();getAccessToken is called before every request, so it can return a refreshed token. For a fixed token, pass token instead.
A service user's API key is sent as X-API-Key; the edge exchanges it for an access token. Keep API keys on a server: never put one in browser code.
import { configure, listDeployments } from '@hexelstudio/titan-sdk';
configure({ baseURL: 'https://api.hexelstudio.com/v1', apiKey: process.env.HEXEL_API_KEY });
const { data } = await listDeployments();configure() sets the transport that every generated function and flow uses. A server that acts for several callers creates one transport per request instead:
import { createTransport } from '@hexelstudio/titan-sdk';
const request = createTransport({ baseURL: 'https://api.hexelstudio.com/v1', token: callerAccessToken });
const deployments = await request('/titan/management/deployments', { method: 'GET' });Each operation needs a permission in your organization, for example titan:enforcement_deployment:read to read a deployment's policy and titan:enforcement_deployment:create to change it, or titan:approval:decide to decide an approval.
Scope headers
The transport sends the context you give it as headers:
| Context field | Header | Sent on |
|---|---|---|
organizationId | X-Organization-Id | Every request, when set. It must match the organization of your token or key. |
workspaceId | X-Workspace-Id | Every request, when set. The workspace the request acts in. |
environmentId | X-Environment-Id | Every request, when set. Needs a workspace. |
enforcementDeploymentId | Titan-Enforcement-Deployment | Only administration calls (/titan/admin/...: approvals, the Agent Ledger, sessions). |
Titan Cloud serves many organizations from one plane, so every administration call through https://api.hexelstudio.com/v1 must name the deployment it acts on by its enforcement deployment id (td- and 32 hex characters). Without it, or naming another organization's deployment, the call is refused with 403. Read the id from the deployment's policy (enforcement_deployment_id in getDeploymentPolicy).
configure({
baseURL: 'https://api.hexelstudio.com/v1',
apiKey: process.env.HEXEL_API_KEY,
getContext: () => ({ organizationId, workspaceId, enforcementDeploymentId: 'td-0123456789abcdef0123456789abcdef' }),
});A Titan-Enforcement-Deployment header you pass on a single call wins over the context. See Request and response headers for how the API checks them.
Connect an account
connectWithApiKey connects an account for a toolkit with a static key, or with the named credential fields the toolkit's auth config declares:
import { connectWithApiKey } from '@hexelstudio/titan-sdk/flows';
const account = await connectWithApiKey({
authConfigId,
apiKey: process.env.ACME_API_KEY,
account: { toolkit_slug: 'ACME_CRM', workspace_id: workspaceId },
});The key is sent as credentials.access_token, the value Titan hands to the tool at call time. For an OAuth toolkit, use startOAuth and, on your redirect page, completeOAuth(code, state).
To decide what agents may do with the connection, see Policies and approvals.
Errors
A generated function resolves with { data, status, headers } for a 2xx response and throws a TitanError for anything else. TitanError has the HTTP status and the parsed response body:
import { TitanError, decideApproval } from '@hexelstudio/titan-sdk';
try {
await decideApproval({ id: approvalId }, { decision: 'approve' });
} catch (err) {
if (!(err instanceof TitanError)) throw err;
const code = (err.body as { error?: { code?: string } })?.error?.code;
if (err.status === 409 && code === 'APPROVAL_NOT_PENDING') {
// Someone else decided it, or it expired.
} else if (err.status === 403 && code === 'NOT_AN_ELIGIBLE_APPROVER') {
// This person is not in an approval role for the request.
} else {
throw err;
}
}Every Titan error body has the same shape, {"error": {"code": "..."}}, often with a message; branch on status and error.code, never on message. Agent API errors also carry retryable and a request_id. Errors lists the codes.
The flow helpers throw the same TitanError when a step is refused. provisionDeployment throws a ProvisioningError (with the failed operation) when provisioning ends in FAILED_CLOSED.
Retries
- Retry only what can be repeated safely: a
429, a503, or an agent API error withretryable: true, after a back-off. - Creating a deployment takes an
Idempotency-Key;provisionDeploymentsends a new one unless you passidempotencyKey. Pass your own to make a retried create return the same deployment. - An agent's side-effecting capability call needs an
Idempotency-Key(428 IDEMPOTENCY_KEY_REQUIREDwithout one). Reuse the same key when you retry the same call.