AI Agents

AI agents: configuration, publishing, testing

GET`/api/ai-agents`

Required scope: agents.read

Parameter	In	Required
`search`	query	no
`archived`	query	no

bash

curl "https://api.zapyflow.com.br/api/ai-agents" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

POST`/api/ai-agents`

Required scope: agents.write

Request body

Field	Type	Required	Constraints
`name`	`string`	yes	min 2, max 120
`agentType`	`"STANDARD" \| "EXPERT"`	no	—
`description`	`string`	no	max 2000
`language`	`"pt" \| "en" \| "es"`	no	—
`tone`	`string`	no	max 4000
`greetingMessage`	`string`	no	max 4000
`fallbackMessage`	`string`	no	max 4000
`outOfHoursMessage`	`string`	no	max 4000
`businessHours`	`object`	no	—
`services`	`object[]`	no	—
`rules`	`object`	no	—
`behavior`	`object`	no	—
`functionKey`	`string`	no	min 1, max 80
`faqs`	`object[]`	no	≤ 200 items
`templateId`	`string`	no	min 1

bash

curl -X POST "https://api.zapyflow.com.br/api/ai-agents" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

201 — Created
403 — Forbidden, or the key lacks this scope

GET`/api/ai-agents/{id}`

Required scope: agents.read

Parameter	In	Required
`id`	path	yes

bash

curl "https://api.zapyflow.com.br/api/ai-agents/{id}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

PATCH`/api/ai-agents/{id}`

Required scope: agents.write

Parameter	In	Required
`id`	path	yes

Request body

Field	Type	Required	Constraints
`name`	`string`	no	min 2, max 120
`agentType`	`"STANDARD" \| "EXPERT"`	no	—
`description`	`string \| null`	no	—
`language`	`"pt" \| "en" \| "es"`	no	—
`tone`	`string \| null`	no	—
`greetingMessage`	`string \| null`	no	—
`fallbackMessage`	`string \| null`	no	—
`outOfHoursMessage`	`string \| null`	no	—
`businessHours`	`object \| null`	no	—
`services`	`object[] \| null`	no	—
`rules`	`object \| null`	no	—
`behavior`	`object \| null`	no	—
`functionKey`	`string \| null`	no	—

bash

curl -X PATCH "https://api.zapyflow.com.br/api/ai-agents/{id}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

200 — OK
412

DELETE`/api/ai-agents/{id}`

Delete an agent that holds no business data

Required scope: agents.lifecycle

Parameter	In	Required
`id`	path	yes

bash

curl -X DELETE "https://api.zapyflow.com.br/api/ai-agents/{id}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace
409 — Conflict with the current state

POST`/api/ai-agents/{id}/archive`

Archive the agent: it leaves the list and stops replying, nothing is lost

Required scope: agents.lifecycle

Parameter	In	Required
`id`	path	yes

bash

curl -X POST "https://api.zapyflow.com.br/api/ai-agents/{id}/archive" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace
409 — Conflict with the current state

GET`/api/ai-agents/{id}/channel-flow-options`

Required scope: agents.read

Parameter	In	Required
`id`	path	yes

bash

curl "https://api.zapyflow.com.br/api/ai-agents/{id}/channel-flow-options" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

GET`/api/ai-agents/{id}/channel-template-options`

Required scope: agents.read

Parameter	In	Required
`category`	query	no
`id`	path	yes

bash

curl "https://api.zapyflow.com.br/api/ai-agents/{id}/channel-template-options" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

GET`/api/ai-agents/{id}/deletion-impact`

What deleting the agent would destroy

Required scope: agents.read

Parameter	In	Required
`id`	path	yes

bash

curl "https://api.zapyflow.com.br/api/ai-agents/{id}/deletion-impact" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

GET`/api/ai-agents/{id}/eval`

Latest boundary-test run and the publishing gate state

Required scope: agents.read

Parameter	In	Required
`id`	path	yes

bash

curl "https://api.zapyflow.com.br/api/ai-agents/{id}/eval" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

POST`/api/ai-agents/{id}/publish`

Required scope: agents.lifecycle

Parameter	In	Required
`id`	path	yes

bash

curl -X POST "https://api.zapyflow.com.br/api/ai-agents/{id}/publish" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
409 — Conflict with the current state

DELETE`/api/ai-agents/{id}/reassign/{targetId}`

Move conversations, leads, appointments and orders to another agent, then delete this one

Required scope: agents.lifecycle

Parameter	In	Required
`id`	path	yes
`targetId`	path	yes

bash

curl -X DELETE "https://api.zapyflow.com.br/api/ai-agents/{id}/reassign/{targetId}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
400 — Malformed request
404 — Not found — also returned when the resource belongs to another workspace
409 — Conflict with the current state

GET`/api/ai-agents/{id}/rules`

The agent's service rules, individually addressable

Required scope: agents.read

Parameter	In	Required
`id`	path	yes

bash

curl "https://api.zapyflow.com.br/api/ai-agents/{id}/rules" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

PATCH`/api/ai-agents/{id}/rules`

Change, remove or add one rule without rewriting the others

Required scope: agents.write

Parameter	In	Required
`id`	path	yes

bash

curl -X PATCH "https://api.zapyflow.com.br/api/ai-agents/{id}/rules" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
400 — Malformed request
404 — Not found — also returned when the resource belongs to another workspace

POST`/api/ai-agents/{id}/unarchive`

Unarchive the agent. It comes back as a draft.

Required scope: agents.lifecycle

Parameter	In	Required
`id`	path	yes

bash

curl -X POST "https://api.zapyflow.com.br/api/ai-agents/{id}/unarchive" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace
409 — Conflict with the current state

POST`/api/ai-agents/{id}/unpublish`

Required scope: agents.lifecycle

Parameter	In	Required
`id`	path	yes

bash

curl -X POST "https://api.zapyflow.com.br/api/ai-agents/{id}/unpublish" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
409 — Conflict with the current state

GET`/api/ai-agents/functions`

Catalog of agent sectors and roles

Required scope: agents.read

bash

curl "https://api.zapyflow.com.br/api/ai-agents/functions" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

GET`/api/ai-agents/overview`

Team KPIs (7 days) and per-agent metrics

Required scope: agents.read

bash

curl "https://api.zapyflow.com.br/api/ai-agents/overview" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

GET`/api/ai-agents/voice-catalog`

Catalog of voices, models and naturalness presets

Required scope: agents.read

bash

curl "https://api.zapyflow.com.br/api/ai-agents/voice-catalog" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

AI Agents

GET/api/ai-agents

POST/api/ai-agents

GET/api/ai-agents/{id}

PATCH/api/ai-agents/{id}

DELETE/api/ai-agents/{id}

POST/api/ai-agents/{id}/archive

GET/api/ai-agents/{id}/channel-flow-options

GET/api/ai-agents/{id}/channel-template-options

GET/api/ai-agents/{id}/deletion-impact

GET/api/ai-agents/{id}/eval

POST/api/ai-agents/{id}/publish

DELETE/api/ai-agents/{id}/reassign/{targetId}

GET/api/ai-agents/{id}/rules

PATCH/api/ai-agents/{id}/rules

POST/api/ai-agents/{id}/unarchive

POST/api/ai-agents/{id}/unpublish

GET/api/ai-agents/functions

GET/api/ai-agents/overview

GET/api/ai-agents/voice-catalog

GET`/api/ai-agents`

POST`/api/ai-agents`

GET`/api/ai-agents/{id}`

PATCH`/api/ai-agents/{id}`

DELETE`/api/ai-agents/{id}`

POST`/api/ai-agents/{id}/archive`

GET`/api/ai-agents/{id}/channel-flow-options`

GET`/api/ai-agents/{id}/channel-template-options`

GET`/api/ai-agents/{id}/deletion-impact`

GET`/api/ai-agents/{id}/eval`

POST`/api/ai-agents/{id}/publish`

DELETE`/api/ai-agents/{id}/reassign/{targetId}`

GET`/api/ai-agents/{id}/rules`

PATCH`/api/ai-agents/{id}/rules`

POST`/api/ai-agents/{id}/unarchive`

POST`/api/ai-agents/{id}/unpublish`

GET`/api/ai-agents/functions`

GET`/api/ai-agents/overview`

GET`/api/ai-agents/voice-catalog`