Conventions & Getting Started
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.
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
-
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 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/tokenwith theclient_credentialsgrant. - Send the key or token on every request as
Authorization: Bearer <key>.
-
Make your first call — list the connectors configured for your org:
A
200with a JSON array means you are set up. A401means theAuthorizationheader is missing or the key is invalid. A404withAPI not foundmeans the Configuration API isn’t turned on for your organization yet: Moveworks turns it on for each organization, so contact your Moveworks team. -
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.
-
Read before you write.
GETthe entity first — updates must echo the currentversion(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 supportGET <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 (noresourcewrapper): -
Update:
PATCHwith a sparse JSON merge-patch as the body. Only the fields present in the patch change; an explicitnullclears a field. For collection entities theidgoes in the URL (PATCH <path>/{id}); anidin the body that doesn’t match it is rejected. Settings documents (one per organization) are patched at<path>itself:
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: {"num": <int>, "change_description": "<audit note>"}.
- On create, send
versionwith only achange_description(nonum). - On every update, echo
version.numfrom a prior read and supply achange_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
GETfirst.
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 —
*_dsland*_benderfields 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/_descsandhandoff_item_action_texts) keyed by the item’sdisplay_keyin the Display config. - An
AGENT_HANDOFFhandoff item’sdisplay_keymust equal a live-agent integration’sname. - Every ticket-routing
workflow_idmust resolve to a workflowdisplay_nameor a built-in*_MW_DEFAULT_*identifier. MS_GRAPHgroup-access sources must be ordered afterACTIVE_DIRECTORY/EXCHANGEones.- Ticketing needs a primary integration setting for tickets to flow.
- A content source’s
connector.auth_methodmust 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
_dsltake a Moveworks DSL (MWDSL) expression — a rule evaluated against a user or ticket."true"= always on / everyone,"false"= off, or an expression likeuser.department IN ["IT", "HR"]. - Fields ending in
_bendertake 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.