API overview
The Smengo API gives programmatic access to your organization's data — employees, departments, the schedule, and other platform resources. It's meant for integrations, BI exports, and automated syncing with external systems, without manually exporting from the UI.
How the API works
The API runs over HTTPS and is versioned in the path: the base URL is https://smengo.com/api/v1. Breaking changes will ship as /api/v2, not as changes to the current version — so existing integrations won't break silently.
Responses are always JSON, including errors. The response format and pagination are described in Conventions.
The API is strictly read-only right now — GET requests only. Write endpoints (creating shifts, check-ins, and so on) are out of scope for v1 and will ship as a separate stage on request.
What's available now
v1 exposes all nine platform resources — each strictly read-only.
Reference resources — available to any valid key for the organization, no scopes required:
GET /org— organization details (name, timezone, locale).GET /departments— the list of departments.GET /shift-presets— shift presets.GET /status-types— status types.
Data resources — each gated by its own scope (see Scopes & permissions):
GET /employees— the list of employees (employees.read).GET /schedule-entries— schedule entries (schedule.read).GET /check-ins— check-ins (checkins.read).GET /timesheets— timesheets (timesheets.read).GET /demand-signals— demand signals (demand.read).
A machine-readable description of the whole API is available as an OpenAPI 3.1 spec: GET /api/v1/openapi.json — public, no key required. To try requests right in your browser, use the interactive console on the /developers page.
The API key is a server secret
Every request is authenticated with an organization API key (see Authentication). Do not use the key in code that runs in a user's browser — CORS is disabled for /api/v1 on purpose, so cross-origin requests won't succeed. Keep the key on your server — in your integration's backend, a script, or a serverless function — and never embed it in client-side JavaScript. There is one exception: the developer console lives on our domain and calls the API same-origin, so you can fire requests by hand there.
What's next
- Authentication — how to get and use a key.
- Quick start — your first request in a couple of minutes.