Skip to main content
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.webhooks
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