Deciders

Update a decider

Updates any of name, description, the backend and questions. Naming agent_id or tool_id replaces the current backend; naming both is 400. Only a change to questions archives a new version; a rename, a new backend or a rewrite of the questions the decider already holds leaves version where it is. A new backend is held to the same rules as on create.

patch/v1/projects/{project_id}/deciders/{decider_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/deciders/{decider_id}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

decider_idstring required
Example:dcd_V1StGXR8Z5jdHi6B

The decider ID

Headers

If-Matchstring

The version the caller believes the resource holds, as an entity tag (3 or "3"). Equivalent to expected_version in the request body; * states no precondition beyond the resource existing. A mismatch is 409 VERSION_CONFLICT.

Request body

namestring
descriptionstring nullable
agent_idstring

Replaces the backend with this agent

tool_idstring

Replaces the backend with this tool

version_labelstring

Optional tag for the version this write archives. Ignored when the write changes no question, since no version is archived.

expected_versioninteger nullable

The version the caller believes the resource holds. When the resource is at any other version the write is refused with 409 VERSION_CONFLICT and nothing is written; meta.current_version on that response names the version in force.

Omit it to write unconditionally. Omitting it does not make the write unordered: two writes that reach the server together are still serialized, and the one whose version was taken first is refused the same way. What the field adds is refusing a write whose author read the resource some time ago and has not seen what happened since.

The If-Match header carries the same precondition for a client that prefers the HTTP spelling. Sending both with different versions is 400 VALIDATION_FAILED.

Example request

{
  "questions": [
    {
      "type": "choice",
      "name": "department",
      "instructions": "Which department should handle this complaint?",
      "choices": [
        {
          "value": "billing",
          "description": "Payments, invoices and refunds."
        },
        {
          "value": "technical",
          "description": "Problems using the product."
        }
      ]
    },
    {
      "type": "predicate",
      "name": "needs_human",
      "instructions": "Must a person read this before any automated reply?"
    }
  ],
  "version_label": "add-account-option",
  "expected_version": 3
}

Response

Decider updated

idstring
project_idstring
namestring
descriptionstring nullable
agent_idstring nullable

The tool-less agent that answers; null when a tool does

tool_idstring nullable

The http or pipeline tool that answers; null when an agent does

versioninteger

The question set's version. Bumped only by a write that changes questions.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "dcd_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "name": "support-triage",
  "agent_id": "agent_V1StGXR8Z5jdHi6B",
  "tool_id": "tool_V1StGXR8Z5jdHi6B",
  "version": 1,
  "questions": [
    {
      "type": "choice",
      "name": "department",
      "instructions": "Which department should handle this complaint?",
      "choices": [
        {
          "value": "billing",
          "description": "Payments, invoices and refunds."
        },
        {
          "value": "technical",
          "description": "Problems using the product."
        }
      ]
    },
    {
      "type": "predicate",
      "name": "needs_human",
      "instructions": "Must a person read this before any automated reply?"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.