Skip to content
Hexel StudioDocs

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.

On this page

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

ImportWhat it has
@hexelstudio/titan-sdkThe platform API: deployments, policy, tools, connections, approvals, the Agent Ledger. configure, createTransport, TitanError.
@hexelstudio/titan-sdk/flowsFlow helpers: provisionDeployment, connectWithApiKey, startOAuth, editPolicy, allowInPolicy and the policy builders.
@hexelstudio/titan-sdk/reactReact Query v5 hooks for the platform API and the flows.
@hexelstudio/titan-sdk/agentThe 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 support@mail.hexelstudio.com for access, then point the @hexelstudio scope at GitHub Packages with a GitHub token that has the read:packages scope:

.npmrc
@hexelstudio:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
Bash
npm install @hexelstudio/titan-sdk

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

WhereBase URL
Titan Cloud and managementhttps://api.hexelstudio.com/v1 (the default)
A Titan Dedicated deploymenthttps://api.hexelstudio.com/v1/cells/<enforcement deployment id>
A deployment's own hostname: everything except managementhttps://<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.

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

configure() sets the transport that every generated function and flow uses. A server that acts for several callers creates one transport per request instead:

TypeScript
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 fieldHeaderSent on
organizationIdX-Organization-IdEvery request, when set. It must match the organization of your token or key.
workspaceIdX-Workspace-IdEvery request, when set. The workspace the request acts in.
environmentIdX-Environment-IdEvery request, when set. Needs a workspace.
enforcementDeploymentIdTitan-Enforcement-DeploymentOnly 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).

TypeScript
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:

TypeScript
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:

TypeScript
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, a 503, or an agent API error with retryable: true, after a back-off.
  • Creating a deployment takes an Idempotency-Key; provisionDeployment sends a new one unless you pass idempotencyKey. 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_REQUIRED without one). Reuse the same key when you retry the same call.