SDK reference

The official Threadline SDK wraps the HTTP API with a small, fully typed surface area.

npm install threadline-sdk

import { Threadline } from "threadline-sdk"

Configuration

Create a client instance with your API key:

const tl = new Threadline({
apiKey: process.env.THREADLINE_KEY!,
baseUrl: process.env.THREADLINE_BASE_URL ?? "https://api.threadline.to",
})

Options:

tl.get

Fetch the raw context object for a user.

const context = await tl.get(userId)

Params:

• userId: string — your stable user identifier (often the same UUID used in Threadline).

Returns:

type ContextObject = {
userId: string
communication_style: string
ongoing_tasks: string[]
key_relationships: string[]
domain_expertise: string[]
preferences: Record<string, unknown>
emotional_state: Record<string, unknown>
last_updated: string
}

Throws ThreadlineError if the user has no context or the key is invalid.

tl.inject

Inject relevant context into a base system prompt.

const injectedPrompt = await tl.inject(userId, basePrompt)

Params:

• userId: string
• basePrompt: string — your original system prompt.

Returns:

Promise<string> — a prompt with a short, natural system prelude that encodes the user's context.

tl.update

Update context from a completed interaction.

await tl.update({
userId,
userMessage,
agentResponse,
})

Params:

• userId: string
• userMessage: string — what the user said/typed.
• agentResponse: string — what your agent replied.

Returns a promise resolving to { updated: boolean; delta: Partial<ContextObject> }. The delta contains only the fields that changed (if any).

tl.grant

Create a scoped grant for another agent.

const { grantId } = await tl.grant({
userId,
agentId,
scopes: ["communication_style", "ongoing_tasks"],
ttlSeconds: 60 * 60 * 24, // optional
})

Params:

• userId: string — the user whose context is being shared.
• agentId: string — the target agent's Threadline id.
• scopes: string[] — fields the agent can access (e.g. "communication_style", "ongoing_tasks").
• ttlSeconds?: number — optional time-to-live; if omitted, the grant doesn't auto-expire.

Returns a promise resolving to { grantId: string }.

tl.revoke

Revoke an existing grant.

await tl.revoke(grantId)

Params:

• grantId: string — id returned from tl.grant.

Returns a promise resolving to { revoked: boolean }.

Errors

All methods throw ThreadlineError:

class ThreadlineError extends Error {
code:
  | "BAD_REQUEST"
  | "UNAUTHORIZED"
  | "FORBIDDEN"
  | "NOT_FOUND"
  | "RATE_LIMITED"
  | "SUPABASE_ERROR"
  | "OPENAI_ERROR"
  | "INTERNAL_ERROR"
  | "NETWORK_ERROR"
  | "UNKNOWN_ERROR"
status?: number
}

Use error.code for programmatic handling and error.message for display.

TypeScript types

The SDK ships with first-class TypeScript support and exports:

• ContextObject — the core user context shape.
• ThreadlineError — error class for all SDK operations.

Import them directly from the package:

import type { ContextObject } from "threadline-sdk"
import { ThreadlineError } from "threadline-sdk"