Client Setup
TrickestClient options, authentication, per-request overrides, idempotency, and the shared http client.
On this page9
Create a client
import { TrickestClient } from '@trickest/sdk'
const client = new TrickestClient({
token: process.env.TRICKEST_TOKEN,
baseUrl: 'https://trickest.io',
wsUrl: process.env.TRICKEST_WS_URL, // optional — agent WebSocket
debug: false,
retry: true, // or { maxRetries: 5, baseDelay: 500 } or false
})TrickestClientOptions
| Option | Source order | Default |
|---|---|---|
token | options.token → TRICKEST_TOKEN | required |
baseUrl | options.baseUrl → TRICKEST_BASE_URL | https://trickest.io |
wsUrl | options.wsUrl → TRICKEST_WS_URL | derived from baseUrl (/ws, ws/wss) |
debug | options.debug | false — logs requests to stderr |
retry | options.retry | true — see Errors & pagination |
If no token is available, the constructor throws immediately:
No API token provided. Pass { token } to TrickestClient or set TRICKEST_TOKEN environment variable.Authorization scheme
The SDK picks the header scheme from the token shape — you do not configure it:
- Token contains
.→Authorization: Bearer <token>(JWT) - Otherwise →
Authorization: Token <token>(API token)
Lazy service namespaces
Services are constructed on first access and cached on the client:
const me = await client.users.getMe() // constructs UsersService once
const again = await client.users.getMe() // reuses cached serviceAll namespaces hang off client.* — see the method index.
Per-request options (RequestOptions)
Every service method accepts an optional trailing RequestOptions object:
await client.workflows.get(workflowId, {
token: process.env.OTHER_USER_TOKEN, // override client token for this call
timeout: 60_000,
signal: abortController.signal,
retry: false,
headers: { 'X-Custom': 'value' },
schema: MyWorkflowSchema, // Zod — parse response before return
idempotencyKey: '550e8400-e29b-41d4-a716-446655440000',
})| Field | Purpose |
|---|---|
timeout | Request timeout in ms (default 30_000) |
signal | AbortSignal for cancellation |
retry | Override client retry for this request |
token | Act as a different user for one call |
schema | Zod schema — schema.parse(body) on success |
idempotencyKey | Idempotency-Key header for safe POST retries |
Idempotency
import { generateIdempotencyKey } from '@trickest/sdk'
const key = generateIdempotencyKey()
await client.workflows.create(spaceId, payload, { idempotencyKey: key })
// Retries with the same key replay the original response instead of creating duplicates.client.http
The public HttpClient on client.http is what every service shares. Use it for ad-hoc
routes not wrapped by a namespace, streaming downloads, or custom pagination:
const raw = await client.http.get<{ ok: boolean }>('/api/auth/session')Import listPage from @trickest/sdk to paginate arbitrary list endpoints:
import { listPage } from '@trickest/sdk'
const page = await listPage(client.http, '/api/workspaces/', { pageSize: 10 })Vault ID
Many calls are vault-scoped (memory, skills, audit, billing). Resolve your vault from the session endpoint:
const session = await client.http.get<{
user: { profile?: { vault_info?: { id?: string } } }
}>('/api/auth/session')
const vaultId = session.user?.profile?.vault_info?.id@trickest/bench uses the same pattern in its config helper.