SDK

@dots/sdk is for building on Dots rather than inside it: calling the platform from your own code, giving a model a supervised way in, adding kinds of things the platform did not ship with, and running what you built inside your own workspace.

It is one typed TypeScript package split into axis-scoped subpath exports — /client, /agent, /mcp, /extend, /customize, /plugin, and /schemas beside the root barrel — so a bundle pulls in only the surface it actually uses. /mcp is the one Node-only entry, and the root barrel never re-exports it.

Five axes organize the surface: Consume, Agent, Extend, Customize, and Distribute.

Key Features

• A typed client. createDotsClient gives you one method per platform capability over a single injectable, retrying transport.
• Errors you branch on, not parse. Each wire error code maps to a class — NotFoundError, ValidationError, AuthError, PermissionDeniedError, ConflictError, ApprovalRequiredError, RateLimitError, UnavailableError — and a code the SDK does not model falls back to the shared DotsSdkError base.
• Pagination as iteration. paginateKeyset and paginateOffset turn listing endpoints into async iterators.
• An agent posture. createDotsAgentClient is the same client with agent mode on, so the Dotabase Operating Manual arrives already parsed beside your data, alongside the <vault-content> helpers that mark retrieved text as untrusted.
• The define* seams. Each pluggable registry has exactly one typed authoring helper in @dots/sdk/extend — defineProperty, defineBehavior, defineMcpTool, defineTemplate, defineLLMProvider, and thirteen more — and SLOT_CATALOG indexes the whole axis so an agent can map it without reading this page.
• Contracts behind the no-code surfaces. The Customize axis exposes saved views, Operation Manuals, property schemas, behavior bindings, tag categories, edge types, page templates, and appearance as typed config contracts an agent can drive.
• Plugins run in a sandbox. A plugin is a dots-plugin.json manifest plus one source module per contributed artifact. No plugin source is evaluated in the daemon process — it executes in the Code Execution Sandbox under the deny-by-default authority its manifest declared.
• A lifecycle CLI. dots plugin init, dots plugin dev, dots plugin build, and dots plugin install carry a plugin from an empty directory to installed.

Get Started

• Build A Plugin — an empty directory to a plugin running inside your workspace, linking the package out of a local Dots checkout. Start here.
• Quickstart: Agents — connect a host to your workspace and scope what it may do.

Resources

• REST API Overview — the versioned HTTP surface the client speaks, for another language or a generated client.
• Row Envelope Format — the record block a row renders as for an agent reader; Agent Envelope is the concept behind it.
• MCP Overview — when the caller is a model rather than your own code.
• Issue Scoped Agent Credentials — give an agent a principal of its own, narrowed to specific permission atoms and an expiry.
• Access And Tenancy — how those atoms resolve into an answer.