@playaos/api-client

Typed JavaScript/TypeScript client for the PlayaOS REST API.

Installation

npm install @playaos/api-client

Quick start

import { createClient } from "@playaos/api-client";

const client = createClient({
  baseUrl: "https://api.playaos.app",
  embedBaseUrl: "https://your-camp.playaos.app",
  apiKey: "pk_live_...",
});

// List members
const members = await client.members.list();

// Filter by role
const admins = await client.members.list({ role: "admin" });

// Get a single member
const member = await client.members.get("uuid-here");

// List applications
const pending = await client.applications.list({ status: "pending", year: 2025 });

// List dues status
const dues = await client.dues.list({ year: 2025 });

// List shifts
const shifts = await client.shifts.list({ publishedOnly: true, year: 2025 });

// Get org config
const org = await client.org.get();

// Submit an application through the embed host
const created = await client.applications.create({
  acknowledged_expectations: true,
  first_name: "Alice",
  last_name: "Smith",
  email: "[email protected]",
  phone: "5551234567",
  birthday: "1990-01-01",
  hometown: "Reno",
  how_heard: "friend",
  burning_man_before: "no",
  shelter_type: "shiftpod_tent",
  ticket_status: "have_ticket",
  build_available: false,
  strike_available: false,
  about_yourself: "I am writing more than fifty characters about myself for this example.",
  agrees_to_principles: true,
});

If your deployment serves both route families from the same host, omit embedBaseUrl and the client will reuse baseUrl.

Route hosts

• baseUrl is used for authenticated /api/v1/* routes.
• embedBaseUrl optionally overrides the host for /api/embed/v1/* routes.
• When embedBaseUrl is omitted, embed requests default to baseUrl.

This is useful when a deployment splits API-key-authenticated routes onto a dedicated API host (for example https://api.playaos.app) but keeps embed routes on a portal host (for example https://your-camp.playaos.app).

Authentication

Generate an API key in Admin → Settings → Developer. Keys use the format pk_live_* and are scoped to specific resources.

Required scopes per endpoint:

| Endpoint | Scope | |----------|-------| | members.list / members.get | members:read | | applications.list | applications:read | | dues.list | dues:read | | shifts.list | shifts:read | | org.get | org:read |

Error handling

import { ApiClientError } from "@playaos/api-client";

try {
  const member = await client.members.get("nonexistent-id");
} catch (err) {
  if (err instanceof ApiClientError) {
    console.error(err.status, err.code, err.message);
    // 404, "NOT_FOUND", "Member not found"
  }
}

MCP server

For AI agent access, use the companion @playaos/mcp package.