Skip to main content
POST
Generate agent completion

Description

This endpoint processes messages for a specific agent, generating a response using one of your AI agents. It can optionally maintain conversation history through threads.

Endpoint

Headers

  • Content-Type: application/json
  • Authorization: Bearer <API_KEY> (required)

Request Body

  • messages: An array of message objects, each containing:
    • role: Either “user” or “assistant”
    • content: The content of the message
  • agentId: The unique identifier of the agent to use for processing
  • parseJson: Whether to try and parse the JSON in the response into a JSON object
  • threadId: (Optional) The ID of an existing thread to continue the conversation

Responses

Success (200 OK)

Returns the generated response, usage information, and thread details.

Error Responses

  • 400 Bad Request: If the request is invalid
  • 401 Unauthorized: If the API key is invalid or the user doesn’t have access to the specified agent
  • 403 Forbidden: If the user doesn’t have enough credits
  • 404 Not Found: If the specified agent or thread is not found

Notes

  • This endpoint uses 10 credits per 1000 total tokens used.
  • The agent must belong to the project owned by the authenticated user.
  • If no threadId is provided, a new thread will be created automatically.
  • Messages are stored in the thread for conversation history.

Rate Limiting

Rate limiting is applied based on the user’s subscription.

Example Request

Example Response

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Parameters required to request an agent completion.

agentId
string
required

Identifier of the agent to run.

messages
object[]
required

Ordered conversation history sent to the agent.

threadId
string

Optional thread identifier for continuing a previous conversation.

parseJson
boolean

When true, attempt to parse the final response as JSON.

requestSource
enum<string>

Optional identifier describing where the API request originated.

Available options:
API,
WEB,
MAKE_DOT_COM,
ZAPIER,
N8N,
PLAYGROUND,
DEFAULT_AUTOMATION,
AGENT_PREVIEW,
AGENT_LIVE,
AUTOPILOT,
STUDIO

Response

Agent completion returned.

text
string
required
stepsTaken
integer
required
steps
object[]
required
tokenUsage
object
required
creditUsage
integer
required
threadId
string
required
parsedJson

Parsed JSON extracted from the final assistant text when parseJson is true.