Introduction

Welcome to the Atomicwork API

The Atomicwork API gives you programmatic access to the core capabilities of your agentic service management platform — so you can extend Atomicwork to fit the way your organisation works.

Whether you're syncing data with internal tools, triggering service actions from external systems, or building entirely new experiences on top of Atomicwork, the API puts the full power of the platform in your hands.

With the Atomicwork API, you can:

• Create and manage requests — programmatically open incidents, service requests, and general tickets, and update them as work progresses.
• Automate workflows — trigger and orchestrate service processes without manual intervention, directly from your own systems.
• Integrate with your existing stack — connect Atomicwork to the tools, platforms, and pipelines your teams already rely on.
• Access and sync data — read user, asset, and request data to power reporting, dashboards, and cross-system visibility.

Authentication

Every request must include your API key in the X-Api-Key header:

X-Api-Key: <your-api-key>

Generate an API key from Settings > My account > Credential store in your Atomicwork workspace (the page title reads Public API token). Keys are workspace-scoped — a key created in one workspace cannot access another.

[!NOTE] These API keys authenticate calls made into Atomicwork. If you need to store credentials for calls going out to external systems from workflows, use the organization-level credential store at Settings > Organization > Security > Credential store. See Managing credentials for details.

Workspace scoping

Most endpoints are scoped to a workspace. Endpoints that take the workspace in the URL (for example POST /api/v1/workspaces/{workspace_id}/requests/list) use the path parameter; endpoints that create a record (for example POST /api/v1/requests/create) take a numeric workspace_id field in the request body:

{ "workspace_id": 48, "request_type": "INCIDENT", "subject": "..." }

There is no workspace header. If a create call omits workspace_id, the record is created in the tenant's default workspace, so always set it explicitly. See Creating requests, incidents and problems.

Your workspace ID is visible in Settings → Workspace or returned by GET /api/v1/workspaces.

Base URL

https://{tenant}.atomicwork.com/api/v1

Replace {tenant} with your Atomicwork subdomain (e.g. acme.atomicwork.com).

Filtering

Many list endpoints accept structured filters that let you narrow results by any entity field. Filters can be passed as the request body (an array) or inside a filters field on the request object. Each filter specifies an attribute, an operator, and a values array:

[
  { "attribute": "status",     "operator": "IS_ANY_OF",  "values": [{"value": "OPEN"}, {"value": "IN_PROGRESS"}] },
  { "attribute": "created_at", "operator": "IS_BETWEEN", "values": [{"value": "2024-01-01T00:00:00Z"}, {"value": "2024-12-31T23:59:59Z"}] }
]

Refer to each endpoint's documentation for the list of supported attributes and operators.

Pagination

Offset-based endpoints accept page (1-indexed) and per_page (default 25, max 100). Cursor-based endpoints return a next_page_token in the response — pass it on the next request to fetch the following page. When next_page_token is absent, you have reached the last page.

Error handling

All errors follow a consistent JSON envelope:

{ "error": "human-readable message", "code": "ERROR_CODE" }

Rate limits

Rate limits are applied per tenant and shared across every channel — Portal, API, Email, Slack, Teams, workflows, and journeys all draw from the same budget. They are not per user and not per API key.

When you hit a limit

The API returns HTTP 429. The back-off interval is included in the response two ways — use whichever is easier for your integration:

• A Retry-After response header, in seconds.
• variables[0] in the JSON body, the same number.

{
  "message": "Rate limit exceeded. Retry after N seconds",
  "message_code": "RATE_LIMIT_ERROR",
  "variables": [N]
}

Wait the full interval before retrying. A call rejected by the 10-minute window may already have counted against the 1-minute window, so an immediate retry can be rejected again.

Bulk migrations

If you're running a one-time data migration and need higher throughput, limits can be raised temporarily for your tenant. Contact your Atomicwork representative with the peak rate you need and how long you need it, and we'll stage the increase ahead of your run.