Niucore

API reference

Agents

Agent definitions and the detail of the tasks a turn ran.

List agents

GETapi.niucore.com/api/v1/agents

Scope: agents:read

Agents visible to the credential, ordered by name. Includes your own inactive ones so their owner can see them; those cannot be attached to a turn.

Note

agents:read does not enable delegation and agents:use does not enable reading definitions: they are two strict scopes. To know which agents a turn can use, read the agents block of `GET /chat/catalog`.

Query

pageintegerdefaults to 1

Page number, starting at 1.

sizeintegerdefaults to 50

Items per page. Maximum 200.

Returns

idinteger

Identifier.

namestring

Name.

descriptionstring | null

What it is for.

tagstring | null

Work domain (finance, support…).

levelstring

Agent scope.

visibilitystring

private, shared or public.

is_activeboolean

An inactive agent of your own shows up when reading but cannot be attached to a turn and is not in the chat catalog.

is_anchoredboolean

Mandatory for the company.

versioninteger

Definition version.

model_idinteger | null

Fixed model for its tasks. null = inherits the turn's. As conductor (principal_agent_id) it always uses the turn's model.

created_atstring (date-time)

Creation.

updated_atstring (date-time)

Last edit.

Errors

  • 503api_v1_agents_disabledAgents are temporarily disabled in the API (meta.error_details.retry_action: "none"). History and task detail remain available.
curl -sS -X GET 'https://api.niucore.com/api/v1/agents' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Response
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "id": 4,
      "name": "Contador",
      "description": "Cierra el mes y revisa asientos.",
      "tag": "finanzas",
      "level": "user",
      "visibility": "private",
      "is_active": true,
      "is_anchored": false,
      "version": 3,
      "model_id": null,
      "created_at": "2026-09-19T21:50:10Z",
      "updated_at": "2026-09-23T10:02:44Z"
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77",
    "page": 1,
    "size": 50,
    "total": 1
  }
}

Retrieve an agent

GETapi.niucore.com/api/v1/agents/{agent_id}

Scope: agents:read

Detail of one definition, with instructions and persona.

Path

agent_idintegerrequired

Identifier.

Returns

idinteger

Identifier.

namestring

Name.

descriptionstring | null

What it is for.

tagstring | null

Work domain (finance, support…).

levelstring

Agent scope.

visibilitystring

private, shared or public.

is_activeboolean

An inactive agent of your own shows up when reading but cannot be attached to a turn and is not in the chat catalog.

is_anchoredboolean

Mandatory for the company.

versioninteger

Definition version.

model_idinteger | null

Fixed model for its tasks. null = inherits the turn's. As conductor (principal_agent_id) it always uses the turn's model.

instructionsstring

Detail only. Canonical form, with {{type:id}} citations as-is: reading the definition does not authorize loading what it cites.

personaobject

Detail only. Tone traits.

created_atstring (date-time)

Creation.

updated_atstring (date-time)

Last edit.

Errors

  • 404api_v1_not_foundIt does not exist, or it is outside the credential's scope. Both cases answer the same.
  • 503api_v1_agents_disabledAgents are temporarily disabled in the API (meta.error_details.retry_action: "none"). History and task detail remain available.
curl -sS -X GET 'https://api.niucore.com/api/v1/agents/4' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Response
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": {
    "id": 4,
    "name": "Contador",
    "description": "Cierra el mes y revisa asientos.",
    "tag": "finanzas",
    "level": "user",
    "visibility": "private",
    "is_active": true,
    "is_anchored": false,
    "version": 3,
    "model_id": null,
    "created_at": "2026-09-19T21:50:10Z",
    "updated_at": "2026-09-23T10:02:44Z",
    "instructions": "Sos el contador de la empresa. Buscá en {{workspace:31}} antes de responder.",
    "persona": {
      "tone": "formal",
      "verbosity": "brief",
      "language": "es"
    }
  },
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77"
  }
}

Agent tasks of a message

GETapi.niucore.com/api/v1/chats/{chat_id}/messages/{message_id}/agent-runs

Scope: chat:read

Durable state of the tasks a turn ran: summary plus brief, steps, messages between tasks and result. Includes temporary, failed and cancelled tasks, and survives the agent being deleted later.

It is this credential's history: it requires chat:read, and agents:read does not grant access to other chats. Another credential of the same user, another chat, another message or a deleted chat answer 404.

Note

It retrieves what was stored; it does not replay the stream. Steps carry no tool arguments or results; the brief, lists and result are bounded, and truncated: true tells you when something was cut.

Path

chat_idstring (uuid)required

Chat.

message_idintegerrequired

Message (turn).

Query

pageintegerdefaults to 1

Page number, starting at 1.

sizeintegerdefaults to 50

Items per page. Maximum 200.

Returns

task_idstring

Opaque correlation for the task within the message. It is the same in message.step, message.action_required, the terminal and the history. It authorizes nothing: an approval is resolved with its action_id.

agent_idinteger | null

null for a temporary agent.

namestring

Name at run time.

kindstring

user or temporal.

tagstring | null

Tag.

statestring

submitted, working, waiting, input_required, paused, completed, failed or cancelled.

reasonstring | null

Reason for an externally requested terminal.

modelstring | null

Effective model.

providerstring | null

Effective provider.

model_requestedstring | null

Fixed model the definition requested.

fallback_reasonstring | null

Why the requested model was not used.

operation_outcomestring | null

not_dispatched, applied or unknown. `unknown` is not a safe retry, even if the turn was cancelled.

retry_safeboolean | null

Whether repeating the task is safe.

tokensobject

The task's input_tokens, output_tokens, total_tokens. Already included in the turn's usage.total_tokens.

started_atstring | null

Start.

finished_atstring | null

End.

updated_atstring | null

Last write.

briefobject | null

Brief: objective, output_format, tools_guidance, boundaries, inputs, label.

stepsarray

{ title, status, detail?, tools? }.

messagesarray

Messages between tasks: { from_name, state, content, created_at }. They are data, not user instructions.

resultstring | null

Task result.

truncatedboolean

Something was cut.

Errors

  • 404api_v1_not_foundIt does not exist, or it is outside the credential's scope. Both cases answer the same.
curl -sS -X GET 'https://api.niucore.com/api/v1/chats/3f6b1a90-6c2d-4d84-a0b1-9d0f5e7c2ab3/messages/90214/agent-runs' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Response
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "task_id": "task_6f0d2a9b41c8e7735a10bd42",
      "agent_id": 4,
      "name": "Contador",
      "kind": "user",
      "tag": "finanzas",
      "state": "completed",
      "reason": null,
      "model": "gpt-4o",
      "provider": "openai",
      "model_requested": null,
      "fallback_reason": null,
      "operation_outcome": "applied",
      "retry_safe": null,
      "tokens": {
        "input_tokens": 1840,
        "output_tokens": 312,
        "total_tokens": 2152
      },
      "started_at": "2026-09-25T10:00:01Z",
      "finished_at": "2026-09-25T10:00:19Z",
      "updated_at": "2026-09-25T10:00:19Z",
      "brief": {
        "objective": "Conciliar los asientos de agosto.",
        "output_format": "Tabla con diferencias."
      },
      "steps": [
        {
          "title": "Buscando en tus bibliotecas",
          "status": "completed",
          "tools": [
            "search_documents"
          ]
        }
      ],
      "messages": [],
      "result": "Hay dos asientos sin contrapartida: 4471 y 4502.",
      "truncated": false
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77",
    "page": 1,
    "size": 50,
    "total": 1
  }
}