Agents API

Base path: /builder/v1/agents. Authentication with Authorization: Bearer <token>. Operations act on the authenticated user's agents. Attributes in camelCase, dates in ISO 8601 UTC.

Agent object

Field	Type	Description
id	string (UUID)	Identifier.
name	string	Name.
description	string or null	Description.
type	single or multiple	Individual or team.
status	published, paused, needs_attention, permissions_required, archived	Status.
requests	integer	Accumulated queries.
createdAt, updatedAt	string	Dates.

Example

curl "https://api.<tu-dominio>/builder/v1/agents?perPage=2&sort=updatedAt" \
  -H "Authorization: Bearer <token>"

{
  "data": [
    {
      "id": "73d2a8dd-51bf-42bc-bc6e-3ff7cd0d03f9",
      "name": "Asistente de políticas",
      "description": "Responde preguntas sobre el reglamento interno",
      "type": "single",
      "status": "published",
      "requests": 12,
      "scope": "global",
      "workflowId": null,
      "createdAt": "2026-08-20T15:02:11Z",
      "updatedAt": "2026-08-25T09:41:03Z"
    }
  ],
  "meta": { "page": 1, "perPage": 2, "total": 7, "totalPages": 4 }
}

scope indicates whether the agent is reusable (global) or private to a workflow (workflow, with workflowId). Agents private to a workflow do not appear in the Agentes de IA (AI Agents) list.

Operations

GET /builder/v1/agents

Parameter	Default	Description
page	1	Page.
perPage	20	Items per page, maximum 100.
search		Search by name, case-insensitive.
status		Filter by status; accepts a comma-separated list.
type		Filter by type; accepts a list.
sort	updatedAt	name, createdAt, updatedAt, requests.
order	desc	asc or desc.

POST /builder/v1/agents

Creates an agent with default values (name "Nuevo agente", type single, status published). No body. Accepts the Idempotency-Key header (UUID): if it is repeated within 24 hours, it returns the earlier creation instead of creating another agent.

GET /builder/v1/agents/{id}, PATCH /builder/v1/agents/{id}, DELETE /builder/v1/agents/{id}

Read, modify and delete. DELETE is a soft delete: the agent is no longer listed and its runs are kept.

GET /builder/v1/models

Models available for configuring agents.

Errors

HTTP	code	When
400	invalid_query	Invalid parameters.
401	unauthorized	No token or invalid token.
404	agent_not_found	It does not exist, is not yours, or was deleted. The three cases are not distinguished.

{ "error": { "code": "agent_not_found", "message": "Agent not found" } }

The full OpenAPI, with the configuration details (instructions, tools, sources), is served from your installation at /builder/v1/openapi.json.