/api/v1/agents/{id}/execute

POST

const url = 'https://api.endless.zaia.app/api/v1/agents/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/execute';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"context":"example","messages":[{"attachments":[{"base64":"example","extension":"png"}],"content":"example","role":"assistant"}],"output":{"properties":{"additionalProperty":{"description":"example","enum":["example"],"examples":["example"],"nullable":true,"type":"string"}},"required":["example"],"type":"object"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.endless.zaia.app/api/v1/agents/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/execute \
  --header 'Content-Type: application/json' \
  --data '{ "context": "example", "messages": [ { "attachments": [ { "base64": "example", "extension": "png" } ], "content": "example", "role": "assistant" } ], "output": { "properties": { "additionalProperty": { "description": "example", "enum": [ "example" ], "examples": [ "example" ], "nullable": true, "type": "string" } }, "required": [ "example" ], "type": "object" } }'

Executes an agent with provided messages.

Parameters

Path Parameters

required

A UUID v4 string that identifies an entity.

string format: uuid

A UUID v4 string that identifies an entity.

Request Body^required

application/json

object

context

string

messages

required

Array<object>

>= 1 items

object

attachments

required

Array

One of:

object

base64

required

A base64 encoded string with prefix.

string

/^data:.*;base64,/

extension

required

string

Allowed values: png

content

required

string

role

required

Any of:

string
string

string

Allowed values: assistant

output

A JSON Schema definition object

object

properties

required

object

key

additional properties

One of:

object

description

string

enum

Array

examples

Array

nullable

boolean

type

required

string

Allowed values: string number integer boolean null

required

Array<string>

type

required

string

Allowed values: object

Responses

200

The agent was executed.

application/json

object

attachmentsUrls

required

Array<string>

content

required

Any of:

string
object

string

execution

required

object

createdAt

required

string format: date-time

required

A UUID v4 string that identifies an entity.

string format: uuid

updatedAt

required

string format: date-time

creditsUsed

required

The total number of credits used by this execution.

number

detail

required

Any of:

object

input

required

The input data for this execution.

object

key

additional properties

nullable

output

required

The output data for this execution.

object

key

additional properties

nullable

agentId

required

The agent identifier.

string

events

required

The events that occurred during this agent execution.

Array

Any of:

object
object

object

creditsUsed

required

The number of credits used by this event.

number

endedAt

required

When this event ended.

string format: date-time

nullable

required

The event identifier.

string

input

Any of:

unknown
object

The input data for this event.

nullable

label

required

The label for this event.

string

>= 3 characters <= 50 characters

llmUsages

The custom-provider LLM usages recorded for this event.

Array<object>

object

inputTokens

required

The input token count reported by the LLM provider.

integer

nullable

model

required

The model key used for this LLM usage.

string

outputTokens

required

The output token count reported by the LLM provider.

integer

nullable

provider

required

The provider metadata associated with this LLM usage.

object

required

The provider ID associated with the LLM usage, when one exists.

string

nullable

name

required

The display name of the provider associated with the LLM usage.

string

>= 3 characters <= 50 characters

output

required

The output data for this event.

object

key

additional properties

nullable

startedAt

required

When this event started.

string format: date-time

status

required

The status of the event.

string

Allowed values: running completed failed skipped

llm

required

The model key used during the iteration event.

string

llmProvider

required

The provider metadata associated with the iteration event.

object

required

The provider ID associated with the LLM usage, when one exists.

string

nullable

name

required

The display name of the provider associated with the LLM usage.

string

>= 3 characters <= 50 characters

type

required

The event subtype represented by this payload.

string

Allowed values: iteration

origin

required

Any of:

object

apiKeyId

required

The API key identifier.

string

type

required

The execution origin subtype represented by this payload.

string

Allowed values: api

type

required

The execution detail subtype represented by this payload.

string

Allowed values: agent-execution

endedAt

required

When this execution ended.

string format: date-time

nullable

isAgentic

required

Whether this execution is agentic.

boolean

isFailedAttempt

required

Whether this execution belongs to a failed retry attempt.

boolean

isPurged

required

Whether this execution has been purged.

boolean

parentId

required

The parent execution ID of this execution.

string format: uuid

nullable

responderId

required

The responder ID of this execution.

string

startedAt

required

When this execution started.

string format: date-time

status

required

The status of the execution.

string

Allowed values: running completed failed cancelled

workspaceId

required

The workspace ID of this execution.

string

Example

{
  "execution": {
    "detail": {
      "events": [
        {
          "status": "running",
          "type": "iteration"
        }
      ],
      "origin": {
        "type": "api"
      },
      "type": "agent-execution"
    },
    "status": "running"
  }
}

401

Unauthorized.

application/json

The description of a known exception.

object

code

The error code.

string

cta

The error call-to-action.

object

type

required

string

Allowed values: support-contact

url

required

string format: uri

feedback

required

The error feedback.

object

enUs

string

esEs

string

ptBr

string

message

required

The error message.

string

name

required

The error name.

string

Example

{
  "cta": {
    "type": "support-contact"
  }
}

404

Agent not found.

application/json

The description of a known exception.

object

code

The error code.

string

cta

The error call-to-action.

object

type

required

string

Allowed values: support-contact

url

required

string format: uri

feedback

required

The error feedback.

object

enUs

string

esEs

string

ptBr

string

message

required

The error message.

string

name

required

The error name.

string

Example

{
  "cta": {
    "type": "support-contact"
  }
}

/api/v1/agents/{id}/execute

Parameters

Path Parameters

Request Bodyrequired

Responses

200

Example

401

Example

404

Example

Request Body^required