Skip to navigation

Conventions & Getting Started

View as Markdown

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 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:

    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):

    {"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:

    {"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.