> This page is for API Reference & Tools.

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

# Conventions & Getting Started

> Make your first Configuration API call and learn the request format, versioning and validation rules every endpoint shares.

The Moveworks Configuration API lets you manage your organization's Moveworks
configuration — connectors, ticketing, search content, access skills, approvals,
and assistant settings — programmatically over plain JSON/HTTPS. Everything you
can configure in the Setup UI today is available through this API, with the same
validations applied.

> **Alpha: limited use only**
>
> The Configuration API is in alpha (`v1alpha1`). It's available only to a limited set of organizations, for setup work done with Moveworks. Don't build integrations against it: paths, fields and behavior can change or be removed without notice.

## Getting started

1. **Get an API key.** Go to **HTTP Connectors > Credentials** and click
   **Create**. Name the credential, choose **API Key** as the credential type,
   and click **Publish**. Copy the key right away: it's shown only once. See
   [API Credentials](/api-reference/api-credentials) for the full steps.

   * A credential belongs to one organization, and calls made with it act as
     the user who created it. Use a dedicated service account rather than a
     personal account.
   * For short-lived tokens instead of a key that doesn't expire, choose
     **OAuth 2.0 Client** as the credential type, then exchange the client ID
     and secret for an access token at `https://api.moveworks.ai/oauth/v1/token`
     with the `client_credentials` grant.
   * Send the key or token on every request as
     `Authorization: Bearer <key>`.
2. **Make your first call** — list the connectors configured for your org:

   ```bash
   curl -H "Authorization: Bearer $MOVEWORKS_API_KEY" \
     https://api.moveworks.ai/configurations/v1alpha1/platform/connectors
   ```

   A `200` with a JSON array means you are set up. A `401` means the
   `Authorization` header is missing or the key is invalid. A `404` with
   `API not found` means the Configuration API isn't turned on for your
   organization yet: Moveworks turns it on for each organization, so contact
   your Moveworks team.
3. **Find your entity.** Every configuration entity has its own section in
   the sidebar, grouped by area: an Overview page with the field table, then one
   page per endpoint with the request and response schema and an example.
4. **Read before you write.** `GET` the entity first — updates must echo the
   current `version` (see *Versioning* below), and several settings documents
   already exist for your org from day one.

## Basics

* **Base URL:** `https://api.moveworks.ai/configurations/v1alpha1`
* **Auth:** `Authorization: Bearer <MOVEWORKS_API_KEY>` on every request. The
  token identifies your organization — org identifiers never appear in URLs.
* **Content type:** `application/json`.
* **Rate limit:** 120 requests per minute per organization. Above that the API
  returns `429` — back off and retry.
* **Delete only for SSO connections.** No other entity can be deleted through
  this API today — create carefully and reuse existing records where possible.

## Reading and writing

Every entity follows one convention:

* **List / read:** `GET <path>` (collections also support `GET <path>/{id}`).
  Responses are **unwrapped** — a bare JSON object for a single document, a bare
  array for a list.

* **Create:** `POST <path>` with the fields at the top level of the JSON body
  (no `resource` wrapper):

  ```json
  {"name": "my-config", "...": "...", "version": {"change_description": "first version"}}
  ```

* **Update:** `PATCH` with a **sparse JSON merge-patch** as the body. Only the
  fields present in the patch change; an explicit `null` clears a field. For
  collection entities the `id` goes in the URL (`PATCH <path>/{id}`); an `id` in
  the body that doesn't match it is rejected. Settings documents (one per
  organization) are patched at `<path>` itself:

  ```json
  {"description": "new text", "version": {"num": 3, "change_description": "updated description"}}
  ```

Each entity's sidebar panel lists its endpoints, with the request and response
schema, an example and the errors for each.

## Versioning (optimistic concurrency)

Every document carries a `version` object: `&#123;"num": &lt;int>,
"change_description": "&lt;audit note>"}`.

* On create, send `version` with only a `change_description` (no `num`).
* On every update, **echo `version.num` from a prior read** and supply a
  `change_description` — it is required and becomes the audit trail.
* If someone else changed the document since your read, the API rejects the
  write with a conflict error — re-read and retry.
* Settings documents (plugin settings, ticket behaviour, notification settings,
  the assistant account) exist from day one and already carry a version —
  always `GET` first.

## Lists and maps replace wholesale

* Array fields **replace wholesale**: the list you send becomes the stored
  list. Rows carry a server-assigned `item_ref` — echo it back so existing rows
  keep their identity.
* Map fields (for example display-label maps) also replace wholesale: a patch
  carrying a map must include every key it wants to keep.

## What the API validates

Every write goes through the same validation the Setup UI applies:

* **Permission (RBAC) checks** — the token must be allowed to write the entity.
* **Mandatory-field checks** — missing required fields are rejected with a
  field-level error message.
* **Allowed-value checks** — enum fields (external systems, auth methods, …)
  only accept the values listed on the entity's reference page.
* **DSL and Bender syntax checks** — `*_dsl` and `*_bender` fields are parsed
  and rejected on syntax errors.

## What the API does NOT validate (check these yourself)

References **between** entities are not checked at write time — a dangling
reference surfaces later, when the configuration is published. The big ones:

* Handoff items need **display labels** (`handoff_item_names`/`_descs` and
  `handoff_item_action_texts`) keyed by the item's `display_key` in the Display
  config.
* An `AGENT_HANDOFF` handoff item's `display_key` must equal a live-agent
  integration's `name`.
* Every ticket-routing `workflow_id` must resolve to a workflow
  `display_name` or a built-in `*_MW_DEFAULT_*` identifier.
* `MS_GRAPH` group-access sources must be ordered after
  `ACTIVE_DIRECTORY`/`EXCHANGE` ones.
* Ticketing needs a **primary** integration setting for tickets to flow.
* A content source's `connector.auth_method` must match how the backing
  connector actually authenticates.

## DSL and Bender fields

Two field families accept small configuration languages; both are validated at
write time:

* Fields ending in `_dsl` take a **Moveworks DSL (MWDSL)** expression — a rule
  evaluated against a user or ticket. `"true"` = always on / everyone,
  `"false"` = off, or an expression like `user.department IN ["IT", "HR"]`.
* Fields ending in `_bender` take a **Bender** data-mapping definition — how
  fields from your system map into Moveworks fields.

Both languages are documented with grammar, function catalog, and worked
examples on the **MWDSL & Bender** page.