OpenMates SDKs

OpenMates provides JavaScript and Python SDKs for API-key access to app skills, chat workflows, and CLI-parity account/product operations.

For the complete method list, see SDK Reference. For the generated test coverage matrix, see SDK Test Coverage Matrix.

API Keys

Create an API key in Settings > Developers > API Keys. The guided flow asks for scope, credit limit, and expiration before revealing the key once. Copy the entire setup credential, including the part after the dot. The SDK sends only the bearer part before the dot; the second part stays in your client and opens client-wrapped encryption keys.

API keys made before this separation are disabled for online SDK access. Revoke each older key in web Settings, create a replacement, and update the applications using it. SDK bearer clients cannot create or revoke other API keys; those methods raise unavailable_requires_first_party_verification. Use verified web Settings or an authenticated CLI session for key management.

For a limited key with project:read, select the personal Projects it may decrypt during creation. The browser wraps only those selected Project keys with the local setup secret. npm and pip Project list and show return cleartext for those Projects; unselected Projects are omitted or rejected. A limited key receives no account master key. Existing Project ciphertext needs no migration. Task and Plan contents, Team Projects, and Projects created after the key was issued do not yet receive limited-key grants; create a replacement key with the desired current Projects when its access needs change.

Defaults are intentionally convenient but powerful:

• Full access is enabled by default.
• Credit usage is unlimited by default.
• Expiration is Never by default.

Each default shows a warning before the key is created. New SDK devices are blocked until approved in Settings > Developers > Devices.

JavaScript

Install the npm package:

npm install openmates

Package page: openmates on npm

import { OpenMates } from "openmates";

const om = new OpenMates({ apiKey: process.env.OPENMATES_API_KEY });

const search = await om.apps.web.search({
  requests: [{ query: "OpenMates SDK examples" }],
});

You do not need to call connect(). SDK methods authenticate lazily with the API key.

List the latest account chats. The default limit is 10 for fast loading; pass limit: 0 only when you intentionally want all account chats:

const chats = await om.chats.list({ limit: 10 });
const allChats = await om.chats.list({ limit: 0 });

Create a non-persistent chat. This is the default and does not save the transcript to your OpenMates account:

const response = await om.chats.send("Summarize this release note draft.");

Create a saved account chat explicitly:

await om.chats.send("Create a project kickoff checklist.", { saveToAccount: true });

Use named namespaces for CLI-parity operations:

await om.account.info();
await om.billing.overview();
await om.billing.invoices();
await om.docs.search("api keys");

SDK chat deletion/sharing, billing exports/downloads, connected-account import, memories, assistant feedback, and benchmarks are available through named SDK methods. Debug-log sharing remains CLI-only and returns a typed unavailable error in SDKs.

Workflow Automation

Author Workflows from YAML when you want the same server-side validation and compilation as the CLI:

const source = `
title: Morning rain check
trigger:
  type: manual
steps: []
`;

const validation = await om.workflows.validateYaml(source);
if (validation.draft_valid) {
  const { workflow } = await om.workflows.createFromYaml(source);
  await om.workflows.enable(workflow.id);
}

Structured callers can still create or modify graph workflows directly:

const workflow = await om.workflows.create({
  title: "Morning rain check",
  enabled: false,
  graph: {
    version: 1,
    trigger_node_id: "trigger",
    nodes: [{ id: "trigger", type: "manual_trigger", config: {} }],
    edges: [],
  },
});

await om.workflows.update(workflow.id, { enabled: true });

Run Workflows with a stable idempotency key, poll run detail, inspect retained node outputs, cancel active runs, or answer an ask_for_user_input step:

const run = await om.workflows.run(workflow.id, {
  idempotencyKey: `rain-check-${Date.now()}`,
  mode: "manual",
  input: { city: "Berlin" },
});

const detail = await om.workflows.runDetail(workflow.id, run.id);
for (const nodeRun of detail.node_runs ?? []) {
  console.log(nodeRun.node_id, nodeRun.status, nodeRun.output_summary);
}

await om.workflows.respond(workflow.id, run.id, "ask-city", { city: "Berlin" });
await om.workflows.cancelRun(workflow.id, run.id);

Python

Install the Python package:

pip install openmates

Package page: openmates on PyPI

from openmates import OpenMates

om = OpenMates()  # reads OPENMATES_API_KEY

result = om.apps.web.search({
    "requests": [{"query": "OpenMates SDK examples"}],
})

List latest account chats. The default limit is 10 for fast loading; pass limit=0 only when you intentionally want all account chats:

chats = om.chats.list(limit=10)
all_chats = om.chats.list(limit=0)

Create a non-persistent chat:

response = om.chats.send("Summarize this release note draft.")

Create a saved account chat explicitly:

om.chats.send("Create a project kickoff checklist.", save_to_account=True)

Use named namespaces for CLI-parity operations:

om.account.info()
om.billing.overview()
om.billing.invoices()
om.docs.search("api keys")

SDK chat deletion/sharing, billing exports/downloads, connected-account import, memories, assistant feedback, and benchmarks are available through named SDK methods. Debug-log sharing remains CLI-only and returns a typed unavailable error in SDKs.

Workflow Automation

Use YAML when you want server-side validation and compilation parity with the CLI:

source = """
title: Morning rain check
trigger:
  type: manual
steps: []
"""

validation = om.workflows.validate_yaml(source)
if validation["draft_valid"]:
    created = om.workflows.create_from_yaml(source)
    workflow = created["workflow"]
    om.workflows.enable(workflow["id"])

Structured callers can create and modify graph workflows directly:

workflow = om.workflows.create(
    title="Morning rain check",
    enabled=False,
    graph={
        "version": 1,
        "trigger_node_id": "trigger",
        "nodes": [{"id": "trigger", "type": "manual_trigger", "config": {}}],
        "edges": [],
    },
)

om.workflows.update(workflow["id"], enabled=True)

Run Workflows, inspect retained per-node outputs, cancel active runs, or answer ask_for_user_input steps:

run = om.workflows.run(
    workflow["id"],
    idempotency_key="rain-check-2026-07-14",
    mode="manual",
    input_data={"city": "Berlin"},
)

detail = om.workflows.run_detail(workflow["id"], run["id"])
for node_run in detail.get("node_runs", []):
    print(node_run.get("node_id"), node_run.get("status"), node_run.get("output_summary"))

om.workflows.respond(workflow["id"], run["id"], "ask-city", {"city": "Berlin"})
om.workflows.cancel_run(workflow["id"], run["id"])

Task lookup limits

The npm and pip SDKs request up to 500 Tasks, the API’s existing maximum, when listing or resolving a Task ID. The Task API currently provides neither continuation paging nor an exact-ID read endpoint, so this does not guarantee lookup across more than 500 matching Tasks.

For larger workspaces, pass a narrower supported filter, such as externalChat (npm), external_chat (pip), or a Project/Team filter, to Task operations. The same filters must be supplied when showing or editing a Task outside the initial bounded list.

Scopes

Chat scopes are enforced server-side:

• chat:create_incognito allows non-persistent SDK chats.
• chat:create_saved allows saved account chats.
• chat:read_existing allows listing existing account chats, including chats.list({ limit }).
• chat:append_existing allows adding messages to existing saved chats.
• chat:delete allows deleting chats.
• chat:share allows creating share links.

App-skill scopes can allow all apps, specific apps, or specific skills such as web:search. SDK app skills are exposed as generated native methods such as om.apps.web.search(...) and om.apps.images.generate(...); public docs do not promote a generic apps.run(...) escape hatch.

Memory access requires memory:read. SDK callers must explicitly load and select memory IDs; the backend does not pause SDK requests to ask the user for memory-selection confirmation.

Errors

SDKs return typed errors for:

• Missing OPENMATES_API_KEY.
• Expired or revoked API keys.
• New or unapproved SDK devices.
• Missing scopes.
• Credit limits that would be exceeded.

Credit limits can use exactly one period: daily, weekly, monthly, or lifetime.