SDK Reference

@grepticon/sdk is the typed TypeScript client for the Grepticon /v1 API. One GrepticonClient wraps one credential and exposes every management operation across workspaces, files, tokens, and audit, plus the read sessions an agent uses. This page is the exhaustive surface; for the end-to-end walkthrough from 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. Pass your grp_sk_ management key for full access. To read as a scoped grp_at_ token instead, prefer a standalone GrepticonSession (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 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 as { 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 GrepticonSession, the workspace-bound read surface an agent navigates with ls / find / cat / grep. Sessions are stateless: each call is one request. 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' });

429s are retried automatically; see Error handling.

GrepticonSession

A standalone read session for a runtime that holds only a token: a browser, an edge worker, or one agent per end user. It reads exactly like client.session(ws), but you build it directly from a grp_at_ token, so it has no management key and no control-plane surface. Reach for it wherever you can't put a grp_sk_ key.

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

const session = new GrepticonSession({ token, workspace: 'handbook' });
const { text } = await session.grep({ pattern: 'onboarding' });

GrepticonSessionOptions

client.session(ws) and new GrepticonSession(...) return the same GrepticonSession shape, so createVfsTools accepts either (and so does core's in-process session, which the eval harness uses).

Exports

@grepticon/sdk exports:

• GrepticonClient: the client class.
• GrepticonSession: the standalone read session (above).
• GrepticonError: the management-call error. See errors.
• Types: GrepticonClientOptions, GrepticonSessionOptions, FetchLike, RetryOption, and the re-exported contract types TokenMintedBody, ToolEnvelope, and ToolStatus.

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.