SDK Reference

@grepticon/sdk is the typed TypeScript client for the Grepticon /v1 API. One GrepticonClient wraps one credential and exposes every management operation (workspaces, files, tokens, audit) plus read sessions an agent uses. This page is the exhaustive surface; for the end-to-end walkthrough — signup to agent answer — follow the Quickstart.

npm install @grepticon/sdk

The AI-SDK adapter lives at the @grepticon/sdk/ai-sdk subpath and needs ai (the Vercel AI SDK) as a peer. The base client has no runtime dependencies beyond fetch.

GrepticonClient

Construct a client with a bearer credential. The same class serves both credential planes — pass a grp_sk_ management key for full access, or a grp_at_ access token for a read-only, single-workspace client (see Authentication).

import { GrepticonClient } from '@grepticon/sdk';

const client = new GrepticonClient({
  apiKey: process.env.GREPTICON_API_KEY ?? '',
});

GrepticonClientOptions

client.workspaces

Create, list, and delete the isolated filesystems your files live in. Management calls throw GrepticonError on any non-2xx response.

await client.workspaces.create('handbook');
const workspaces = await client.workspaces.list();

client.files

Upload, delete, list, and await ingestion of files. Uploads are asynchronous — see async ingestion.

files.upload(ws, path, content, opts?)

Uploads a file and returns { path, status } — status is 'pending' right after upload. content is a string or Uint8Array.

await client.files.upload(
  'handbook',
  'guides/onboarding.md',
  '# Onboarding\n\nNew hires finish setup on day one.\n',
  { contentType: 'text/markdown' },
);

files.delete(ws, path)

Removes a file from the workspace. Returns void.

files.list(ws, opts?)

Returns a page of file entries: { files, nextCursor }. Each entry is { path, status, sizeBytes, contentType, updatedAt, errorDetail }. Follow nextCursor (a string or null) to page through the whole workspace.

files.waitForReady(ws, opts?)

Polls until uploads finish ingesting — the practical way to close the async gap where an upload returns 'pending' but reads can't see it yet. A file is settled once it reaches 'ready' or 'error'. Resolves with the settled file entries.

const [file] = await client.files.waitForReady('handbook', {
  paths: ['guides/onboarding.md'],
});
if (file?.status === 'error') {
  throw new Error(`Ingestion failed: ${file.errorDetail ?? 'unknown error'}`);
}

client.tokens

Mint and revoke the scoped, read-only grp_at_ access tokens you hand to agents. There is no list endpoint — a token can only be minted or revoked, so keep the id if you intend to revoke it later.

tokens.mint(ws, opts?)

Mints a grp_at_ token scoped to ws and returns { id, token, claims, expiresAt }. The plaintext token is returned exactly once — it is never retrievable again.

const { id, token } = await client.tokens.mint('handbook', {
  ttlSeconds: 600,
});

tokens.revoke(id)

Revokes a token by its id (from mint). Takes effect on the next request. Returns void.

client.audit

audit.export(ws, opts?) returns a page of read-audit events — { events, nextCursor } — for compliance or debugging. Each event records the tool, actor, params, result count, latency, and timestamp. Options mirror the paging shape: { after?: string; cursor?: string; limit?: number }. Most integrations never need this; reach for it when you want a record of what an agent read.

client.session(ws)

Returns a VfsReadSession — the workspace-bound read surface an agent navigates with ls / find / cat / grep. Sessions are stateless (each call is one request) and, unlike management calls, read tools return a { text, status } envelope instead of throwing on not_found / bad_request. The error model covers this split, and the AI-SDK adapter turns a session into the four agent tools.

const session = client.session('handbook');
const { text } = await session.grep({ pattern: 'onboarding' });

Retries and 429s

Reads are rate-limited; a throttled request returns 429 with a Retry-After header. By default the client retries a 429 twice, honoring Retry-After (bounded to a 1–10 second wait), before surfacing the error — so bursty agent traffic mostly rides through untouched. Only 429 is retried; other errors (and 5xx) are not.

// Tune or disable the retry budget:
new GrepticonClient({ apiKey, retry: { retries: 5 } });
new GrepticonClient({ apiKey, retry: false });

RetryOption is false | { retries?: number }.

Exports

@grepticon/sdk exports:

• GrepticonClient — the client class.
• GrepticonError — the management-call error (errors).
• Types: GrepticonClientOptions, FetchLike, RetryOption, and the re-exported contract types TokenMintedBody, ToolEnvelope, ToolStatus, and VfsReadSession.

The AI-SDK adapter is a separate import: createVfsTools from @grepticon/sdk/ai-sdk.

Where to go next

• AI-SDK adapter — createVfsTools(session) and the four tools.
• Error handling — the throw-vs-envelope model and retries.
• Quickstart — the full loop this surface powers.