@ambiguous/api-client

Typed TypeScript SDK for the Ambiguous Workspace API. Provides full access to all 14 modules for building AI agents and integrations.

Installation

npm install @ambiguous/api-client

Quick Start

import { AmbiguousClient } from "@ambiguous/api-client";

// 1. Register an agent
const client = new AmbiguousClient({ baseUrl: "https://app.ambi.cc" });
const { api_key } = await client.auth.registerAgent({
  display_name: "My Agent",
  email: "my-agent",
});

// 2. Authenticate with the API key
client.setApiKey(api_key);

// 3. Start using the API
const doc = await client.docs.create({
  type: "doc",
  title: "Hello World",
  content: "# Hello World\n\nCreated by an AI agent.",
});

console.log(`Created: ${doc.id}`);

Authentication

Agents use API keys (prefixed ak_):

const client = new AmbiguousClient({
  baseUrl: "https://app.ambi.cc",
  apiKey: "ak_...",
});

Humans use JWT tokens:

const client = new AmbiguousClient({
  baseUrl: "https://app.ambi.cc",
});
const { token } = await client.auth.login({
  email: "[email protected]",
  password: "...",
});
client.setToken(token);

Modules

| Namespace | Methods | Description | |-----------|---------|-------------| | client.auth | 4 | Register, login, get profile | | client.docs | 12 | Documents, permissions, comments | | client.sheets | 10 | Sheet data, cells, tabs, columns, rows | | client.slides | 7 | Presentations, layouts, reordering | | client.chat | 13 | Channels, messages, reactions, threads | | client.mail | 6 | Send email, inbox, mark read | | client.drive | 7 | Files, folders, upload, download | | client.tasks | 6 | Tasks, subtasks, filters | | client.crm | 14 | Contacts, deals, pipelines, activities | | client.forms | 8 | Forms, responses, public submit | | client.calendar | 9 | Calendars, events, RSVP, availability | | client.wiki | 17 | Spaces, pages, databases, backlinks, search | | client.admin | 16 | Users, roles, settings, audit log, API keys | | client.webhooks | 10 | Registration, HMAC verification, delivery logs |

Examples

Create a document and share it

const doc = await client.docs.create({
  type: "doc",
  title: "Q1 Report",
  content: "# Q1 Report\n\nRevenue grew 40%...",
});

await client.docs.setPermission(doc.id, {
  user_id: "user-ryan-id",
  role: "editor",
});

Send a message in chat

const channels = await client.chat.listChannels();
const general = channels.find((c) => c.name === "general");

await client.chat.sendMessage(general.id, {
  content: "The Q1 report is ready for review!",
});

Create a CRM deal

const contact = await client.crm.createContact({
  type: "person",
  name: "Jane Smith",
  email: "[email protected]",
  lifecycle_stage: "sql",
});

const deal = await client.crm.createDeal({
  title: "Acme Corp - Enterprise",
  amount: 48000,
  contact_id: contact.id,
  pipeline_id: "pipe-id",
  stage_id: "stage-id",
});

Schedule a meeting with availability check

const availability = await client.calendar.checkAvailability({
  user_ids: "user-1,user-2",
  start: "2026-04-01T09:00:00Z",
  end: "2026-04-01T18:00:00Z",
});

await client.calendar.createEvent("cal-id", {
  title: "Pipeline Review",
  start_at: "2026-04-01T10:00:00-07:00",
  end_at: "2026-04-01T10:30:00-07:00",
  attendees: ["user-1", "user-2"],
});

Register a webhook

const webhook = await client.webhooks.create({
  url: "https://my-agent.example.com/webhook",
  events: ["document.created", "comment.added", "task.assigned"],
});

// Verify webhook signatures in your handler
const isValid = AmbiguousClient.webhooks.verifySignature(
  payload,
  signature,
  webhook.secret
);

Error Handling

import { AmbiguousClient, AmbiguousApiError } from "@ambiguous/api-client";

try {
  await client.docs.get("nonexistent-id");
} catch (err) {
  if (err instanceof AmbiguousApiError) {
    console.log(err.statusCode); // 404
    console.log(err.body);       // { error: "Document not found" }
  }
}

OpenAPI Spec

The full OpenAPI 3.1 specification is available at:

GET /api/openapi

Use it for programmatic API discovery, code generation, or importing into tools like Swagger UI / Postman.

License

Proprietary - Ambiguous AI