Skip to main content

Use the API base URL

The production base URL is:
Append the operation’s path, including /c/{companyId}. Use HTTPS and Authorization: Bearer <token>. Send Content-Type: application/json when a request has a JSON body.

Identify your workspace

The public {companyId} path parameter accepts either a stable company ID or a workspace URL slug. Use the company ID for durable integration configuration because a workspace slug can change.
  • Workspace slug: open your workspace in the Dashboard and copy the value after /s/ in the browser URL. For /s/example-workspace/config/api-keys, the slug is example-workspace.
  • Company ID: ask Windmill support for your workspace’s company ID and include the workspace slug. You can start with the slug while obtaining the ID; you don’t need an undocumented API call.
Store your chosen value in WINDMILL_COMPANY_ID. The name of this environment variable doesn’t change which identifiers the server accepts. API keys and OAuth tokens remain restricted to their authorized company.

Keep identifiers distinct

An employee ID identifies a person in the org chart. A member identifies workspace access, and a user identifies an account. Use employee IDs returned by employee search in employee paths. Treat IDs as opaque strings; don’t derive them from names or email addresses.

Read employee profiles

After creating a read key, set these environment variables locally:
Searches use POST to accept structured JSON filters. This operation only reads data. A synthetic successful response is:
The response has no data wrapper. pagination.total is omitted unless you request include: { "total": true }. Use Get an employee profile when you need the additional fields documented for an individual employee.

Choose filters and write fields

Employee searches and counts default to filter.status: "CURRENT". Use "FORMER" for archived employees or "ALL" for both. Each nested and/or filter also defaults to CURRENT; set status: "ALL" on nested filters that should include archived employees. For a count without filters, send an explicit JSON object:
For writes, use the exact fields in the operation reference. Create an employee uses primaryEmail. Explicit ownership claims on profile updates use claimOwnership. Field-source requests use public source identifiers such as bamboo-hr, google-workspace, and just-works; discover the allowed sources with List available employee field sources. Review pagination, rate limits, and error handling before sending recurring or write requests.