Postman Collection

Every endpoint of the EmbayLMS public API is available as a ready-to-run Postman collection, with an environment you fill in once and sample code in more than twenty languages for every request. The collection is generated from the API’s own OpenAPI specification on every release, so it always matches the endpoints that actually exist — it cannot go stale.

Prerequisites: an EmbayLMS API key (see Getting Started, Step 1) and a free Postman account or the Postman web app.

Step 1: Import the collection

Choose either path:

Public workspace (recommended): open the EmbayLMS public workspace on Postman — search for EmbayLMS — Public API in Postman’s public API network — and click Fork (or Run in Postman) to copy the collection and its environment into your own workspace. Forks receive updates when you click Pull changes.
From the OpenAPI spec: in Postman choose Import and paste your tenant’s spec URL, https://{your-tenant}.embaylms.com/api/v1/docs. Postman builds a collection from the spec. It has the same endpoints, but not the tests, the id chaining or the environment described below, so prefer the public workspace when you can. After importing, open the collection’s Variables and set baseUrl to https://{your-tenant}.embaylms.com/api/v1 (the spec’s server URL keeps {slug} as a placeholder), then on the collection’s Authorization tab choose Bearer Token and paste your API key.

From the public workspace you get one collection, EmbayLMS — Public API, with a folder per resource (Plans, Completions, Users, Enrollments, Courses, Reports, Groups, LTI 1.3), and one environment, EmbayLMS — Public API.

Step 2: Configure the environment

Select the EmbayLMS — Public API environment (top-right in Postman) and set two values:

Variable	Type	Description
`tenantSlug`	default	Your tenant’s subdomain — the `acme` in `acme.embaylms.com`.
`apiKey`	secret	An API key from Settings → Integrations → API Keys (`ems_live_…`). Stored as a Postman secret: masked in the UI and never exported with the collection.
`readOnly`	default	Optional. Set to `true` to skip every non-GET request when you run the whole collection — a safe smoke test against production.

The collection derives baseUrl (https://{{tenantSlug}}.embaylms.com/api/v1) from the slug, and sends the key as Authorization: Bearer {{apiKey}} on every request except GET /plans and the LTI protocol endpoints, which are anonymous by design.

Step 3: Send your first request

Open Users → List users and press Send. The response is the standard { data, meta, error } envelope, and the Test Results tab shows the checks that ran: the status code, the envelope shape, and the pagination fields.

List requests also store the first row’s id in a collection variable (userId, courseId, enrollmentId, groupId), so the Get …, Update … and Delete … requests below them resolve without copying ids by hand. A by-id request whose id has not been seeded yet is skipped with a note rather than failing.

Step 4: Get sample code in your language

Open any request and click the </> (Code) icon in the right-hand rail. Postman generates a working snippet for that exact request — headers, query parameters and body included — in cURL, JavaScript (fetch / Axios), Node.js, Python (requests / http.client), Java, C#, Go, PHP, Ruby, Swift, Kotlin, PowerShell and more. Change a parameter in the request and the snippet updates.

Running the whole collection

Use Postman’s Collection Runner (or Newman on the command line) to execute every request in order with its tests:

npx newman run embaylms-public.postman_collection.json \
  -e embaylms-public.postman_environment.json \
  --env-var readOnly=true

With readOnly=true only GET requests run — the writes (create user, enroll, delete…) are skipped — so a run against a production tenant changes nothing. Leave it unset against a sandbox tenant to exercise the writes too.

How the collection stays current

The collection is not maintained by hand. It is generated from the OpenAPI specification served at GET /api/v1/docs on your tenant — the same specification that is checked in CI against the implemented routes — and the public workspace is updated on every release. A request in the collection is therefore always a request the API answers; new endpoints appear in the collection the day they ship, and a deprecated endpoint is flagged in its description with the sunset date (see Versioning & Deprecation).

Troubleshooting

Symptom	Cause	Fix
`401 Unauthorized` on every request	`apiKey` is empty, or the environment is not selected	Select EmbayLMS — Public API top-right and set `apiKey`; the key is shown once at creation — create a new one if lost.
`403 API access is not included in your plan`	The tenant is on a tier without API access	API access is a Growth-and-above capability — see Plans.
`getaddrinfo ENOTFOUND your-tenant.embaylms.com`	`tenantSlug` still holds the placeholder	Set it to your real subdomain.
A Get … request shows skipped	Its id variable was never seeded in this run	Run the matching List … request first (or set `userId` / `courseId` … by hand in the collection variables).
`429 Too Many Requests` during a run	Collection Runner exceeded the per-key limit	Add a delay between requests in the Runner, or see Rate Limits.
Tests fail with body is the { data, meta, error } envelope	The response was not JSON (e.g. `format=csv` on the transcript)	Expected for download endpoints; the check only runs on JSON responses.

Getting Started — create a key and make your first call
Authentication — key format, scopes, rotation
Errors — the response envelope and every error code

Getting Started Authentication