Agentic Flows

Use an API key or REST OAuth access token. Scopes and your current workspace permissions apply together. All examples are illustrative.

Read Flow configuration catalog

GET /api/external/v1/flow-catalog

Scope: flows:read

Response 200

Success.

Header	Type	Description
Cache-Control	string	The response must not be cached. Example: no-store

application/json

FieldsExample

Field	Type	Description
models	List of object	Models available with the current user's permissions.
routingModes	List of string	Available routing methods. Values: LLM, DECISION
promptVariables	List of object	Prompt variables supported by this configuration.

models — fields

Field	Type	Description
value	string	Exact catalog value to send in API requests. Show all 19 allowed values GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
fixedTemperature	number (double)	Temperature required by this model, if fixed.
maxOutputTokens	integer (int32)	Maximum output-token budget supported by this model.

promptVariables — fields

Field	Type	Description
key	string	Name of the variable or parameter.
label	string	Display label for this value or variable.
helperText	string	Explanation of how to use the prompt variable.
category	string	Category used to group prompt variables. Values: AGENT, ROUTING

{
  "models": [],
  "routingModes": [],
  "promptVariables": []
}

Error responses

Status	Meaning
400	Invalid input, unsupported selection or time range.
401	Missing, expired or invalid credential. The body may be empty.
403	Required scope or current user permission missing. The body may be empty.
429	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
status	integer	HTTP status code.
error	string	Description of the error.
details	any	Additional error details, when available. Rules: null allowed
code	string	Machine-readable error code.
params	object	Additional values associated with the error code.
fieldErrors	object	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Create Agentic Flow

POST /api/external/v1/flows

Scope: flows:write

Saves configuration directly; no call, tool test or message delivery is executed.

Request body · application/json

FieldsExample

Field	Type	Required	Description
title	string	Yes	Display name of the resource. Rules: up to 255 characters Example: "Demo"
description	string	No	Description of this resource's purpose. Rules: up to 255 characters
persona	string	No	Shared personality and speaking style for Agents in this Flow. Rules: up to 100000 characters
routingPrompt	string	No	Instructions for LLM routing. Use variables from the Flow catalog. Rules: up to 100000 characters
model	string	Yes	Routing model from the Flow catalog. Check its temperature and output limits. Show all 19 allowed values GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
conversationHistoryLimit	integer (int32)	Yes	Maximum number of conversation-history entries supplied to the model. Rules: 0–100 Example: 10
temperature	number (double)	Yes	Routing-response variation. Respect any fixed temperature in the Flow catalog. Rules: 0–2 Example: 0.3
maxTokens	integer (int32)	Yes	Maximum output-token budget. Also respect the selected model's limit in the catalog. Rules: 10–25000 Example: 1000
intentAgentMapping	object	Yes	Map intent names to Agent IDs in this workspace. Include DEFAULT as the fallback. Rules: at least 1 key Example: {"DEFAULT": "00000000-0000-0000-0000-000000000001"} Each value: string (uuid)
routingMode	string	Yes	Routing method selected from the Flow catalog. Values: LLM, DECISION
decisionRouting	object	No	Decision-routing settings. Omitting this field or sending null on update keeps the existing draft.

decisionRouting — fields

Field	Type	Required	Description
instructions	string	No	Instructions for choosing a routing intent. Rules: up to 20000 characters
intentDescriptions	object	No	Describe when each active intent applies, including DEFAULT. Each value: string
conversationHistoryLimit	integer (int32)	Yes	Maximum number of conversation-history entries supplied to the model. Rules: 0–100 Example: 10

{
  "title": "Demo",
  "description": "string",
  "persona": "string",
  "routingPrompt": "string",
  "model": "GPT_4_1_MINI",
  "conversationHistoryLimit": 10,
  "temperature": 0.3,
  "maxTokens": 1000,
  "intentAgentMapping": {
    "DEFAULT": "00000000-0000-0000-0000-000000000001"
  },
  "routingMode": "LLM",
  "decisionRouting": {
    "instructions": "string",
    "intentDescriptions": {},
    "conversationHistoryLimit": 10
  }
}

Response 201

Created.

Header	Type	Description
Cache-Control	string	The response must not be cached. Example: no-store
Location	string	Path of the created resource.
ETag	string	Current revision. Send unchanged, including quotes, as If-Match when required. Example: "revision-from-get"

application/json

FieldsExample

Field	Type	Description
id	string (uuid)	Resource ID in your workspace.
revision	string	Current resource revision. Use the response ETag for If-Match when updating.
configuration	object	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
title	string	Display name of the resource. Rules: up to 255 characters Example: "Demo"
description	string	Description of this resource's purpose. Rules: up to 255 characters
persona	string	Shared personality and speaking style for Agents in this Flow. Rules: up to 100000 characters
routingPrompt	string	Instructions for LLM routing. Use variables from the Flow catalog. Rules: up to 100000 characters
model	string	Routing model from the Flow catalog. Check its temperature and output limits. Show all 19 allowed values GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
conversationHistoryLimit	integer (int32)	Maximum number of conversation-history entries supplied to the model. Rules: 0–100 Example: 10
temperature	number (double)	Routing-response variation. Respect any fixed temperature in the Flow catalog. Rules: 0–2 Example: 0.3
maxTokens	integer (int32)	Maximum output-token budget. Also respect the selected model's limit in the catalog. Rules: 10–25000 Example: 1000
intentAgentMapping	object	Map intent names to Agent IDs in this workspace. Include DEFAULT as the fallback. Rules: at least 1 key Example: {"DEFAULT": "00000000-0000-0000-0000-000000000001"} Each value: string (uuid)
routingMode	string	Routing method selected from the Flow catalog. Values: LLM, DECISION
decisionRouting	object	Decision-routing settings. Omitting this field or sending null on update keeps the existing draft.

decisionRouting — fields

Field	Type	Description
instructions	string	Instructions for choosing a routing intent. Rules: up to 20000 characters
intentDescriptions	object	Describe when each active intent applies, including DEFAULT. Each value: string
conversationHistoryLimit	integer (int32)	Maximum number of conversation-history entries supplied to the model. Rules: 0–100 Example: 10

{
  "id": "00000000-0000-0000-0000-000000000001",
  "revision": "revision-from-get",
  "configuration": {
    "title": "Demo",
    "description": "string",
    "persona": "string",
    "routingPrompt": "string",
    "model": "GPT_4_1_MINI",
    "conversationHistoryLimit": 10,
    "temperature": 0.3,
    "maxTokens": 1000,
    "intentAgentMapping": {
      "DEFAULT": "00000000-0000-0000-0000-000000000001"
    },
    "routingMode": "LLM",
    "decisionRouting": {
      "instructions": "string",
      "intentDescriptions": {},
      "conversationHistoryLimit": 10
    }
  }
}

Error responses

Status	Meaning
400	Invalid input, unsupported selection or time range.
401	Missing, expired or invalid credential. The body may be empty.
403	Required scope or current user permission missing. The body may be empty.
409	Missing/stale revision or dependency/routing conflict. Read again before retrying.
429	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
status	integer	HTTP status code.
error	string	Description of the error.
details	any	Additional error details, when available. Rules: null allowed
code	string	Machine-readable error code.
params	object	Additional values associated with the error code.
fieldErrors	object	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

List Agentic Flows

GET /api/external/v1/flows

Scope: flows:read

Parameters

Name	Location	Type	Required	Description
page	Query	integer (int32)	No	Page index, starting at 0. Rules: 0–100000 Default: 0
size	Query	integer (int32)	No	Results per page. Rules: 1–100 Default: 25

Response 200

Success.

Header	Type	Description
Cache-Control	string	The response must not be cached. Example: no-store

application/json

FieldsExample

Field	Type	Description
items	List of object	Results on this page.
page	integer (int32)	Current page index, starting at 0.
size	integer (int32)	Number of results requested per page.
totalElements	integer (int64)	Total number of matching results.
totalPages	integer (int32)	Total number of result pages.

items — fields

Field	Type	Description
id	string (uuid)	Resource ID in your workspace.
revision	string	Current resource revision. Use the response ETag for If-Match when updating.
title	string	Display name of the resource.
description	string	Description of this resource's purpose.
routingMode	string	Routing method selected from the Flow catalog. Values: LLM, DECISION

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "revision": "revision-from-get",
      "title": "NuvoCar service",
      "description": "string",
      "routingMode": "LLM"
    }
  ],
  "page": 0,
  "size": 25,
  "totalElements": 1,
  "totalPages": 1
}

Error responses

Status	Meaning
400	Invalid input, unsupported selection or time range.
401	Missing, expired or invalid credential. The body may be empty.
403	Required scope or current user permission missing. The body may be empty.
429	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
status	integer	HTTP status code.
error	string	Description of the error.
details	any	Additional error details, when available. Rules: null allowed
code	string	Machine-readable error code.
params	object	Additional values associated with the error code.
fieldErrors	object	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Delete Agentic Flow

DELETE /api/external/v1/flows/{id}

Scope: flows:write

Read the resource first. Send its current ETag, including quotes, in If-Match.

Parameters

Name	Location	Type	Required	Description
id	Path	string (uuid)	Yes	Resource identifier in the bound workspace.
If-Match	Header	string	Yes	ETag from the preceding read, including quotes. Example: "revision-from-get"

Response 204

Deleted; no response body.

Header	Type	Description
Cache-Control	string	The response must not be cached. Example: no-store

Error responses

Status	Meaning
400	Invalid input, unsupported selection or time range.
401	Missing, expired or invalid credential. The body may be empty.
403	Required scope or current user permission missing. The body may be empty.
404	Resource is unavailable in the bound workspace.
409	Missing/stale revision or dependency/routing conflict. Read again before retrying.
429	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
status	integer	HTTP status code.
error	string	Description of the error.
details	any	Additional error details, when available. Rules: null allowed
code	string	Machine-readable error code.
params	object	Additional values associated with the error code.
fieldErrors	object	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Read Agentic Flow

GET /api/external/v1/flows/{id}

Scope: flows:read

Parameters

Name	Location	Type	Required	Description
id	Path	string (uuid)	Yes	Resource identifier in the bound workspace.

Response 200

Success.

Header	Type	Description
Cache-Control	string	The response must not be cached. Example: no-store
ETag	string	Current revision. Send unchanged, including quotes, as If-Match when required. Example: "revision-from-get"

application/json

FieldsExample

Field	Type	Description
id	string (uuid)	Resource ID in your workspace.
revision	string	Current resource revision. Use the response ETag for If-Match when updating.
configuration	object	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
title	string	Display name of the resource. Rules: up to 255 characters Example: "Demo"
description	string	Description of this resource's purpose. Rules: up to 255 characters
persona	string	Shared personality and speaking style for Agents in this Flow. Rules: up to 100000 characters
routingPrompt	string	Instructions for LLM routing. Use variables from the Flow catalog. Rules: up to 100000 characters
model	string	Routing model from the Flow catalog. Check its temperature and output limits. Show all 19 allowed values GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
conversationHistoryLimit	integer (int32)	Maximum number of conversation-history entries supplied to the model. Rules: 0–100 Example: 10
temperature	number (double)	Routing-response variation. Respect any fixed temperature in the Flow catalog. Rules: 0–2 Example: 0.3
maxTokens	integer (int32)	Maximum output-token budget. Also respect the selected model's limit in the catalog. Rules: 10–25000 Example: 1000
intentAgentMapping	object	Map intent names to Agent IDs in this workspace. Include DEFAULT as the fallback. Rules: at least 1 key Example: {"DEFAULT": "00000000-0000-0000-0000-000000000001"} Each value: string (uuid)
routingMode	string	Routing method selected from the Flow catalog. Values: LLM, DECISION
decisionRouting	object	Decision-routing settings. Omitting this field or sending null on update keeps the existing draft.

decisionRouting — fields

Field	Type	Description
instructions	string	Instructions for choosing a routing intent. Rules: up to 20000 characters
intentDescriptions	object	Describe when each active intent applies, including DEFAULT. Each value: string
conversationHistoryLimit	integer (int32)	Maximum number of conversation-history entries supplied to the model. Rules: 0–100 Example: 10

{
  "id": "00000000-0000-0000-0000-000000000001",
  "revision": "revision-from-get",
  "configuration": {
    "title": "Demo",
    "description": "string",
    "persona": "string",
    "routingPrompt": "string",
    "model": "GPT_4_1_MINI",
    "conversationHistoryLimit": 10,
    "temperature": 0.3,
    "maxTokens": 1000,
    "intentAgentMapping": {
      "DEFAULT": "00000000-0000-0000-0000-000000000001"
    },
    "routingMode": "LLM",
    "decisionRouting": {
      "instructions": "string",
      "intentDescriptions": {},
      "conversationHistoryLimit": 10
    }
  }
}

Error responses

Status	Meaning
400	Invalid input, unsupported selection or time range.
401	Missing, expired or invalid credential. The body may be empty.
403	Required scope or current user permission missing. The body may be empty.
404	Resource is unavailable in the bound workspace.
429	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
status	integer	HTTP status code.
error	string	Description of the error.
details	any	Additional error details, when available. Rules: null allowed
code	string	Machine-readable error code.
params	object	Additional values associated with the error code.
fieldErrors	object	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Update Agentic Flow

PUT /api/external/v1/flows/{id}

Scope: flows:write

Saves configuration directly; no call, tool test or message delivery is executed. Read the resource first. Send its current ETag, including quotes, in If-Match. Send the full editable configuration. Omitted settings can be reset.

Parameters

Name	Location	Type	Required	Description
id	Path	string (uuid)	Yes	Resource identifier in the bound workspace.
If-Match	Header	string	Yes	ETag from the preceding read, including quotes. Example: "revision-from-get"

Request body · application/json

FieldsExample

Field	Type	Required	Description
title	string	Yes	Display name of the resource. Rules: up to 255 characters Example: "Demo"
description	string	No	Description of this resource's purpose. Rules: up to 255 characters
persona	string	No	Shared personality and speaking style for Agents in this Flow. Rules: up to 100000 characters
routingPrompt	string	No	Instructions for LLM routing. Use variables from the Flow catalog. Rules: up to 100000 characters
model	string	Yes	Routing model from the Flow catalog. Check its temperature and output limits. Show all 19 allowed values GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
conversationHistoryLimit	integer (int32)	Yes	Maximum number of conversation-history entries supplied to the model. Rules: 0–100 Example: 10
temperature	number (double)	Yes	Routing-response variation. Respect any fixed temperature in the Flow catalog. Rules: 0–2 Example: 0.3
maxTokens	integer (int32)	Yes	Maximum output-token budget. Also respect the selected model's limit in the catalog. Rules: 10–25000 Example: 1000
intentAgentMapping	object	Yes	Map intent names to Agent IDs in this workspace. Include DEFAULT as the fallback. Rules: at least 1 key Example: {"DEFAULT": "00000000-0000-0000-0000-000000000001"} Each value: string (uuid)
routingMode	string	Yes	Routing method selected from the Flow catalog. Values: LLM, DECISION
decisionRouting	object	No	Decision-routing settings. Omitting this field or sending null on update keeps the existing draft.

decisionRouting — fields

Field	Type	Required	Description
instructions	string	No	Instructions for choosing a routing intent. Rules: up to 20000 characters
intentDescriptions	object	No	Describe when each active intent applies, including DEFAULT. Each value: string
conversationHistoryLimit	integer (int32)	Yes	Maximum number of conversation-history entries supplied to the model. Rules: 0–100 Example: 10

{
  "title": "Demo",
  "description": "string",
  "persona": "string",
  "routingPrompt": "string",
  "model": "GPT_4_1_MINI",
  "conversationHistoryLimit": 10,
  "temperature": 0.3,
  "maxTokens": 1000,
  "intentAgentMapping": {
    "DEFAULT": "00000000-0000-0000-0000-000000000001"
  },
  "routingMode": "LLM",
  "decisionRouting": {
    "instructions": "string",
    "intentDescriptions": {},
    "conversationHistoryLimit": 10
  }
}

Response 200

Success.

Header	Type	Description
Cache-Control	string	The response must not be cached. Example: no-store
ETag	string	Current revision. Send unchanged, including quotes, as If-Match when required. Example: "revision-from-get"

application/json

FieldsExample

Field	Type	Description
id	string (uuid)	Resource ID in your workspace.
revision	string	Current resource revision. Use the response ETag for If-Match when updating.
configuration	object	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
title	string	Display name of the resource. Rules: up to 255 characters Example: "Demo"
description	string	Description of this resource's purpose. Rules: up to 255 characters
persona	string	Shared personality and speaking style for Agents in this Flow. Rules: up to 100000 characters
routingPrompt	string	Instructions for LLM routing. Use variables from the Flow catalog. Rules: up to 100000 characters
model	string	Routing model from the Flow catalog. Check its temperature and output limits. Show all 19 allowed values GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
conversationHistoryLimit	integer (int32)	Maximum number of conversation-history entries supplied to the model. Rules: 0–100 Example: 10
temperature	number (double)	Routing-response variation. Respect any fixed temperature in the Flow catalog. Rules: 0–2 Example: 0.3
maxTokens	integer (int32)	Maximum output-token budget. Also respect the selected model's limit in the catalog. Rules: 10–25000 Example: 1000
intentAgentMapping	object	Map intent names to Agent IDs in this workspace. Include DEFAULT as the fallback. Rules: at least 1 key Example: {"DEFAULT": "00000000-0000-0000-0000-000000000001"} Each value: string (uuid)
routingMode	string	Routing method selected from the Flow catalog. Values: LLM, DECISION
decisionRouting	object	Decision-routing settings. Omitting this field or sending null on update keeps the existing draft.

decisionRouting — fields

Field	Type	Description
instructions	string	Instructions for choosing a routing intent. Rules: up to 20000 characters
intentDescriptions	object	Describe when each active intent applies, including DEFAULT. Each value: string
conversationHistoryLimit	integer (int32)	Maximum number of conversation-history entries supplied to the model. Rules: 0–100 Example: 10

{
  "id": "00000000-0000-0000-0000-000000000001",
  "revision": "revision-from-get",
  "configuration": {
    "title": "Demo",
    "description": "string",
    "persona": "string",
    "routingPrompt": "string",
    "model": "GPT_4_1_MINI",
    "conversationHistoryLimit": 10,
    "temperature": 0.3,
    "maxTokens": 1000,
    "intentAgentMapping": {
      "DEFAULT": "00000000-0000-0000-0000-000000000001"
    },
    "routingMode": "LLM",
    "decisionRouting": {
      "instructions": "string",
      "intentDescriptions": {},
      "conversationHistoryLimit": 10
    }
  }
}

Error responses

Status	Meaning
400	Invalid input, unsupported selection or time range.
401	Missing, expired or invalid credential. The body may be empty.
403	Required scope or current user permission missing. The body may be empty.
404	Resource is unavailable in the bound workspace.
409	Missing/stale revision or dependency/routing conflict. Read again before retrying.
429	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
status	integer	HTTP status code.
error	string	Description of the error.
details	any	Additional error details, when available. Rules: null allowed
code	string	Machine-readable error code.
params	object	Additional values associated with the error code.
fieldErrors	object	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.