# MongoDB Atlas Emulator (service host)

Create an instance:
curl -s -X POST https://mongoatlas.emulators.dev/_emulate/instances
# Hosted deployments create instances lazily when the returned URL is first used. The instance URL is a capability: anyone who has it can read and modify the instance, so save the returned URLs. Never store real secrets in an emulator.
# The server generates an unguessable name. An optional {"instance":"<prefix>"} body adds a readable prefix.

Then use the returned providerBaseUrl / controlBaseUrl. Example below uses a sample instance.
# MongoDB Atlas Emulator

Stateful MongoDB Atlas emulator for the Atlas Administration API v2 and the Atlas Data API v1.

Provider base URL: https://mongoatlas.your-instance.emulators.dev
Control base URL: https://mongoatlas.your-instance.emulators.dev/_emulate

Supported surfaces:
- Atlas Admin API: partial at /api/atlas/v2
- Atlas Data API: partial at /api/data/v1

Control endpoints:
- https://mongoatlas.your-instance.emulators.dev/_emulate/manifest
- https://mongoatlas.your-instance.emulators.dev/_emulate/coverage
- https://mongoatlas.your-instance.emulators.dev/_emulate/connections
- https://mongoatlas.your-instance.emulators.dev/_emulate/state
- https://mongoatlas.your-instance.emulators.dev/_emulate/ledger
- https://mongoatlas.your-instance.emulators.dev/_emulate/faults
- POST https://mongoatlas.your-instance.emulators.dev/_emulate/credentials
- POST https://mongoatlas.your-instance.emulators.dev/_emulate/seed
- POST https://mongoatlas.your-instance.emulators.dev/_emulate/reset

Fault injection:
Arm a one-shot provider failure with a glob pathPattern, then inspect /ledger for faulted: true.
curl -s -X POST https://mongoatlas.your-instance.emulators.dev/_emulate/faults \
  -H "content-type: application/json" \
  -d '{"match":{"method":"GET","pathPattern":"/v1/*"},"response":{"status":503,"body":{"error":"temporary"}}}'

Connect:

## Atlas Admin API client (TypeScript)
import { AtlasClient } from "atlas-api-client";

const client = new AtlasClient({
  baseUrl: "https://mongoatlas.your-instance.emulators.dev/api/atlas/v2",
  publicKey: "<client_id>",
  privateKey: "<client_secret>",
});

## Atlas Data API (fetch)
const res = await fetch("https://mongoatlas.your-instance.emulators.dev/app/data-api/v1/action/findOne", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    apiKey: "<token>",
  },
  body: JSON.stringify({
    dataSource: "Cluster0",
    database: "test",
    collection: "items",
    filter: {},
  }),
});
const { document } = await res.json();

## Atlas base URL (env)
MONGODB_ATLAS_BASE_URL=https://mongoatlas.your-instance.emulators.dev
MONGODB_ATLAS_API_KEY=<token>

## curl (Admin API)
curl -s https://mongoatlas.your-instance.emulators.dev/api/atlas/v2/groups -H "authorization: Bearer <token>"

## curl (Data API)
curl -s -X POST https://mongoatlas.your-instance.emulators.dev/app/data-api/v1/action/findOne \
  -H "content-type: application/json" \
  -H "apiKey: <token>" \
  -d '{"dataSource":"Cluster0","database":"test","collection":"items","filter":{}}'

## Base URL (env)
MONGOATLAS_BASE_URL=https://mongoatlas.your-instance.emulators.dev

## Create a credential
curl -s -X POST https://mongoatlas.your-instance.emulators.dev/_emulate/credentials \
  -H "content-type: application/json" \
  -d '{"type":"api-key"}'

## Inspect requests
curl -s https://mongoatlas.your-instance.emulators.dev/_emulate/ledger