Unblocked TypeScript SDK

The official TypeScript SDK for the Unblocked Public API. Its request and response types mirror the public API contract.

Install

bun add @getunblocked/sdk

Create a client

Create a Personal Access Token or Team Access Token in Unblocked under Settings → API Tokens.

import { UnblockedClient } from "@getunblocked/sdk";

const token = process.env.UNBLOCKED_API_TOKEN;

if (!token) {
  throw new Error("UNBLOCKED_API_TOKEN is required");
}

const unblocked = new UnblockedClient({
  token,
  maxRetries: 0,
});

The client also accepts an asynchronous token provider:

const unblocked = new UnblockedClient({
  token: async () => getApiToken(),
  maxRetries: 0,
});

Use the SDK in a trusted server environment. Do not include an Unblocked API token in browser code.

Context

Context operations use one flat namespace:

const research = await unblocked.context.research({
  query: "How does authentication work?",
});

const code = await unblocked.context.searchCode({
  query: "rate limiting",
});

const issues = await unblocked.context.queryIssues({
  query: "Open authentication bugs",
});

const urls = await unblocked.context.getUrls({
  urls: ["https://example.com/document"],
});

The context client also provides:

• searchDocumentation
• searchIssues
• searchMessages
• searchPrs
• queryPrs

Answers

Questions use caller-provided UUIDs and are processed asynchronously:

const questionId = crypto.randomUUID();

await unblocked.answers.ask({
  questionId,
  question: "What changed in authentication this week?",
});

const answer = await unblocked.answers.get({ questionId });

Use answers.list() to list questions. Use answers.delete({ questionId }) to delete one.

Collections

const collection = await unblocked.collections.create({
  name: "Support",
  description: "Customer support documents.",
  iconUrl: "https://example.com/support.png",
});

await unblocked.collections.update({
  collectionId: collection.id,
  body: {
    description: "Current customer support documents.",
  },
});

The collections client also provides list, get, and delete.

Documents

const document = await unblocked.documents.put({
  collectionId: collection.id,
  title: "Password reset guide",
  body: "To reset your password...",
  uri: "https://example.com/password-reset",
});

if (!document.id) {
  throw new Error("The API did not return a document ID");
}

await unblocked.documents.delete({ documentId: document.id });

The id guard is required because the current public OpenAPI contract marks the response field as optional.

Pagination

List methods return the response array. Pagination links are available through the raw response:

const request = unblocked.documents.list({ limit: 25 });
const { data: documents, rawResponse } = await request.withRawResponse();

const link = rawResponse.headers.get("link");

Do not assume that a short page is the final page. Follow the rel="next" link when it is present.

Request options

Each method accepts request options as its second argument:

const request = unblocked.context.research(
  { query: "How does authentication work?" },
  { timeoutInSeconds: 180, maxRetries: 0 },
);

const { data, rawResponse } = await request.withRawResponse();

Requests time out after 120 seconds by default. The SDK defaults to two retries for retryable failures, including operations that are not safe to replay. Set maxRetries: 0 on the client unless your application has an idempotency strategy. You can override the value for an individual request.

Error handling

Non-successful API responses throw status-specific errors generated from the public contract:

import { Unblocked, UnblockedClient } from "@getunblocked/sdk";

try {
  await unblocked.collections.get({ collectionId: crypto.randomUUID() });
} catch (error) {
  if (error instanceof Unblocked.NotFoundError) {
    console.error(error.statusCode, error.body);
  }
}

Network failures and unlisted status codes throw UnblockedError. Timeouts throw UnblockedTimeoutError. Both are root package exports.

Runtime support

• ESM package
• Node.js 18 or later
• Native fetch
• No runtime dependencies