Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt

Use this file to discover all available pages before exploring further.

The Mesa SDK is the primary way to use Mesa and comes with everything you need to get started. It combines:
  • typed access to all REST API operations
  • programmatic control of Mesa filesystems
  • typed Git operations like clone, push, etc.

​
Installation

npm install @mesadev/sdk

​
Quick Start

import { Mesa } from '@mesadev/sdk';

const mesa = new Mesa({
  apiKey: process.env.MESA_API_KEY,
  org: 'acme'
});

// Create anonymous repo
const repo = await mesa.repos.create();

console.log(repo.name); // 01KM1ERQ35G9SESK75V5SQRR97

// Override org per call when needed
const templates = await mesa.repos.list({
  org: 'public-templates',
  limit: 20,
});

​
Configuration

import { Mesa } from '@mesadev/sdk';

const mesa = new Mesa({
  apiKey: process.env.MESA_API_KEY,
  apiUrl: 'https://api.mesa.dev/v1',
  fetch: globalThis.fetch,
  org: 'acme',
  userAgent: 'my-app/1.0.0',
});
Constructor options:
  • apiKey?: string - API key. Falls back to MESA_API_KEY in environment variables
  • apiUrl?: string - API base URL. Defaults to https://api.mesa.dev/v1
  • org?: string - optional default org slug. When omitted, SDK uses your api key to call /whoami in the API to resolve your default org.
  • fetch?: typeof fetch - custom fetch implementation.
  • userAgent?: string - optional user-agent suffix.

​
API Resources

The SDK exposes all current REST resources:
  • mesa.org
  • mesa.repos
  • mesa.content
  • mesa.bookmarks
  • mesa.changes
  • mesa.webhookTargets — CRUD on webhook targets
  • mesa.webhooks — verify and dispatch incoming webhook deliveries
And a low-level escape hatch:
  • mesa.raw.* for direct generated operation access
const whoami = await mesa.raw.getWhoami();
console.log(whoami.org.slug);
For detailed usage of each resource, see Basic Operations. For filesystem and bash operations, see Filesystem API & Bash.

​
Errors

The SDK surfaces typed errors for common setup and lifecycle failures:
  • MissingApiKeyError
  • InvalidApiUrlError
  • OrgResolutionError