> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer-test.atomicwork.com/llms.txt.
> For full documentation content, see https://developer-test.atomicwork.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-test.atomicwork.com/_mcp/server.

# 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 → Integrations → API Keys** in your Atomicwork workspace. Keys are workspace-scoped — a key created in one workspace cannot access another.

## Workspace scoping

Most endpoints are scoped to a workspace. Include the numeric workspace ID in the `X-Workspace-Id` header on every request:

```
X-Workspace-Id: <your-workspace-id>
```

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:

```json
[
  { "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:

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

| HTTP status | Meaning                                                          |
| ----------- | ---------------------------------------------------------------- |
| `400`       | Invalid request — check field values and required parameters     |
| `401`       | Missing or invalid API key                                       |
| `403`       | Insufficient permissions for this operation                      |
| `404`       | Resource not found                                               |
| `429`       | Rate limit exceeded — retry after the `Retry-After` header value |
| `500`       | Internal server error — contact support if persistent            |