TypeScript SDK

import {Custral} from "@custral/sdk";

const custral = new Custral({apiKey: process.env.CUSTRAL_API_KEY!}); // sk_...

// Create a record on any object (requires records:write).
const {id, ignoredFields} = await custral.records.create({
  object: "contacts",
  fields: {email: "jane@acme.com", full_name: "Jane Doe"},
});

const custral = new Custral({
  apiKey: process.env.CUSTRAL_API_KEY!, // required, a secret key (sk_...)
  baseUrl: "https://api.custral.com", // default; use http://localhost:8080 locally
  maxRetries: 2, // retry safe failures (rate limits, 5xx on reads, connection errors)
  timeout: 30_000, // per-request timeout in ms
  webhookSecret: process.env.CUSTRAL_WEBHOOK_SECRET, // default secret for webhook verification
});

// Create (records:write). Always adds a new record; there is no upsert.
const {id, ignoredFields} = await custral.records.create({
  object: "contacts",
  fields: {email: "jane@acme.com", full_name: "Jane Doe"},
});

// List (records:read) — filter, sort, search, and offset OR cursor pagination.
const page = await custral.records.list({
  object: "contacts",
  filter: {external_id: "crm_42"}, // look up by any property, {amount: {gte: "100"}} for operators
  sort: "created_at:desc",
  limit: 50,
});
page.data; // CustralRecord[]
page.total; // number | null
page.hasMore; // boolean
page.nextCursor; // pass back as list({cursor}) for the next page

// Full-text search (relevance-ranked; ignores filter/sort/cursor).
const hits = await custral.records.list({object: "deals", q: "globex" });

// Retrieve one (records:read). Inline notes docs → markdown with expand (needs documents:read).
const record = await custral.records.retrieve({object: "issues", id: "rec_123", expand: ["notes"]});
record.fields.notes; // markdown, not a doc_ id

// Or fetch a document directly by the doc_ id a notes field holds (documents:read).
const {markdown} = await custral.documents.retrieve("doc_3Ab9xK2mQ7");

// Update fields on an existing record (records:write). Only the keys you send
// change; unmatched keys come back in `ignoredFields`.
const {ignoredFields} = await custral.records.update({
  object: "contacts",
  id: "rec_123",
  fields: {status: "customer"},
});

// Create a conversation, link a participant, and import an initial message
// in one call (conversations:write).
const convo = await custral.conversations.create({
  title: "Jane Doe",
  sourceType: "imessage", // free-form label; defaults to "api"
  participants: [{name: "Jane Doe", email: "jane@acme.com"}],
  messages: [{text: "Hey, still on for Friday?", direction: "inbound"}],
});

// Append messages as they arrive (conversations:write). Fans out to live agents.
await custral.conversations.sendMessage(convo.id, {
  text: "Yes. See you at 2pm.",
  author: "You",
  direction: "outbound",
});

// Read the full transcript back (conversations:read).
const full = await custral.conversations.retrieve(convo.id);
full.messages; // CustralMessage[]
full.participants; // CustralParticipant[]

// Manage the lifecycle (conversations:write). Statuses: "open" | "closed" | "completed".
await custral.conversations.update(convo.id, {status: "closed", outcome: "won"});

// List, filtered by status / channel (conversations:read) — offset pagination.
const page = await custral.conversations.list({status: "open", limit: 50});

// Discover the valid `outcome` keys (conversations:read).
const dispositions = await custral.conversations.listDispositions();

const objects = await custral.objects.list(); // objects:read
const object = await custral.objects.retrieve("obj_123");

const me = await custral.me(); // "does my key work, and what can it do?"
me.orgId;
me.environment; // "live" | "test" | null
me.scopes; // ApiKeyScope[]

const {tools, count} = await custral.mcp.tools(); // the tools/list an MCP client sees (mcp:read)

import {Custral, CustralError, CustralRateLimitError} from "@custral/sdk";

try {
  await custral.records.create({object: "deals", fields: {name: "Globex"}});
} catch (err) {
  if (err instanceof CustralRateLimitError) {
    console.warn(`rate limited; retry after ${err.retryAfter}s`);
  } else if (err instanceof CustralError) {
    console.error(`${err.code} (${err.statusCode}) · request ${err.requestId}`);
  }
}

import express from "express";
import {Custral} from "@custral/sdk";

const custral = new Custral({
  apiKey: process.env.CUSTRAL_API_KEY!,
  webhookSecret: process.env.CUSTRAL_WEBHOOK_SECRET!,
});

custral.on("record.created", (event) => saveLead(event.data));
custral.on("record.*", (event) => audit(event)); // prefix glob

const app = express();
app.post("/webhooks/custral", express.raw({type: "application/json"}), custral.webhooks.express());

const event = custral.webhooks.constructEvent(req.body, req.headers["x-custral-signature"], secret);
// throws CustralSignatureVerificationError if missing, stale, or wrong.