Skip to main content

Agent

AI agent chat, conversations, and automation

All endpoints require a bearer token (oh_... API key or user JWT) and are served under https://api.orderly-hub.com. Use the Try it consoles to run a request against the Preview (test) server.

Send message to AI agent​

POST/api/v1/agent/chat

Send a natural language message to the AI agent. The agent uses a 3-phase decision system: (1) rule-based standing order matching, (2) LLM with query+propose tools only, (3) LLM with full execute access if org permits. Write actions go through the pending action approval system.

Request body​

FieldTypeDescription
messagestringNatural language message (max 10,000 chars)
conversationIdstringContinue an existing conversation
contextobjectOptional context to scope the agent's focus
{
"message": "string",
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"context": {
"operationId": "550e8400-e29b-41d4-a716-446655440000",
"orderIds": [
"string"
]
}
}

Responses​

200 Agent response queued

AgentChatResponse object:

FieldTypeDescription
conversationIdstring
statusqueued | processing | completed | error
{
"data": {
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued"
}
}

401 Authentication required

POST/api/v1/agent/chat

Send message to AI agent

https://api-test.orderly-hub.com/api/v1/agent/chat

List agent conversations​

GET/api/v1/agent/conversations

Parameters​

NameInRequiredTypeDescription
pagequerynointeger
limitquerynointeger

Responses​

200 Paginated conversation list

AgentConversation[] object:

FieldTypeDescription
idstring
titlestring
statusactive | archived
messageCountinteger
messagesAgentMessage[]
createdAtstring
updatedAtstring
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "string",
"status": "active",
"messageCount": 0,
"messages": [
{
"id": null,
"role": null,
"content": null,
"inputTokens": null,
"outputTokens": null,
"toolCalls": null,
"createdAt": null
}
],
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
],
"pagination": {
"page": 0,
"limit": 0,
"total": 49.99,
"totalPages": 0,
"hasMore": true
}
}
GET/api/v1/agent/conversations

List agent conversations

https://api-test.orderly-hub.com/api/v1/agent/conversations

Get conversation with messages and tool calls​

GET/api/v1/agent/conversations/{id}

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Responses​

200 Conversation details with messages

AgentConversation object:

FieldTypeDescription
idstring
titlestring
statusactive | archived
messageCountinteger
messagesAgentMessage[]
createdAtstring
updatedAtstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "string",
"status": "active",
"messageCount": 0,
"messages": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"role": "user",
"content": "string",
"inputTokens": 0,
"outputTokens": 0,
"toolCalls": [],
"createdAt": "2026-07-23T12:00:00Z"
}
],
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
}

404 Conversation not found

GET/api/v1/agent/conversations/{id}

Get conversation with messages and tool calls

https://api-test.orderly-hub.com/api/v1/agent/conversations/

Archive a conversation (soft delete)​

DELETE/api/v1/agent/conversations/{id}

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Responses​

200 Conversation archived

Response fields:

FieldTypeDescription
successboolean
{
"success": true
}
DELETE/api/v1/agent/conversations/{id}

Archive a conversation (soft delete)

https://api-test.orderly-hub.com/api/v1/agent/conversations/

List agent memory entries​

GET/api/v1/agent/memory

View organization memory entries stored by the agent.

Parameters​

NameInRequiredTypeDescription
categoryquerynostringFilter by memory category
scope_typequerynostringFilter by scope type

Responses​

200 Memory entries

AgentMemory[] object:

FieldTypeDescription
idstring
keystring
valuestring
categorystring
scopeTypestring
expiresAtstring
createdAtstring
updatedAtstring
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "string",
"value": "string",
"category": "string",
"scopeType": "string",
"expiresAt": "2026-07-23T12:00:00Z",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
]
}
GET/api/v1/agent/memory

List agent memory entries

https://api-test.orderly-hub.com/api/v1/agent/memory

Delete a memory entry​

DELETE/api/v1/agent/memory/{id}

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Responses​

200 Memory entry deleted

Response fields:

FieldTypeDescription
successboolean
{
"success": true
}
DELETE/api/v1/agent/memory/{id}

Delete a memory entry

https://api-test.orderly-hub.com/api/v1/agent/memory/

List pending agent actions​

GET/api/v1/agent/pending-actions

List actions the agent wants to perform that require user approval.

Parameters​

NameInRequiredTypeDescription
statusquerynopending | approved | rejected | expired | allFilter by status (default pending)

Responses​

200 Pending actions

PendingAction[] object:

FieldTypeDescription
idstring
conversationIdstring
toolNamestring
toolInputobject
statuspending | approved | rejected | expired
reviewedBystring
reviewedAtstring
reviewNotestring
expiresAtstring
createdAtstring
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"toolName": "string",
"toolInput": {},
"status": "pending",
"reviewedBy": "string",
"reviewedAt": "2026-07-23T12:00:00Z",
"reviewNote": "string",
"expiresAt": "2026-07-23T12:00:00Z",
"createdAt": "2026-07-23T12:00:00Z"
}
]
}
GET/api/v1/agent/pending-actions

List pending agent actions

https://api-test.orderly-hub.com/api/v1/agent/pending-actions

Approve and execute a pending action​

POST/api/v1/agent/pending-actions/{id}/approve

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Request body​

FieldTypeDescription
notestringOptional approval note
{
"note": "string"
}

Responses​

200 Action approved and executed

Response fields:

FieldTypeDescription
idstring
statusstring
messagestring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"message": "string"
}
}

404 Pending action not found

410 Pending action has expired

POST/api/v1/agent/pending-actions/{id}/approve

Approve and execute a pending action

https://api-test.orderly-hub.com/api/v1/agent/pending-actions//approve

Reject a pending action​

POST/api/v1/agent/pending-actions/{id}/reject

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Request body​

FieldTypeDescription
notestringOptional rejection reason
{
"note": "string"
}

Responses​

200 Action rejected

Response fields:

FieldTypeDescription
idstring
statusstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending"
}
}
POST/api/v1/agent/pending-actions/{id}/reject

Reject a pending action

https://api-test.orderly-hub.com/api/v1/agent/pending-actions//reject

List agent scheduled tasks​

GET/api/v1/agent/scheduled-tasks

List cron-based scheduled tasks for the organization.

Responses​

200 Scheduled tasks

AgentScheduledTask[] object:

FieldTypeDescription
idstring
namestring
descriptionstring
promptstringNatural language prompt executed on schedule
cronExpressionstring
timezonestring
statusactive | paused
lastRunAtstring
nextRunAtstring
createdBystring
createdAtstring
updatedAtstring
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Jane Doe",
"description": "string",
"prompt": "string",
"cronExpression": "string",
"timezone": "string",
"status": "active",
"lastRunAt": "2026-07-23T12:00:00Z",
"nextRunAt": "2026-07-23T12:00:00Z",
"createdBy": "string",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
]
}
GET/api/v1/agent/scheduled-tasks

List agent scheduled tasks

https://api-test.orderly-hub.com/api/v1/agent/scheduled-tasks

Create agent scheduled task​

POST/api/v1/agent/scheduled-tasks

Create a new cron-based scheduled task. Requires agent:admin scope.

Request body​

FieldTypeDescription
namestring
descriptionstring
promptstringNatural language prompt the agent executes on schedule
cronExpressionstringCron expression (e.g. "0 9 * * 1-5")
timezonestring
{
"name": "Jane Doe",
"description": "string",
"prompt": "string",
"cronExpression": "string",
"timezone": "string"
}

Responses​

201 Scheduled task created

AgentScheduledTask object:

FieldTypeDescription
idstring
namestring
descriptionstring
promptstringNatural language prompt executed on schedule
cronExpressionstring
timezonestring
statusactive | paused
lastRunAtstring
nextRunAtstring
createdBystring
createdAtstring
updatedAtstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Jane Doe",
"description": "string",
"prompt": "string",
"cronExpression": "string",
"timezone": "string",
"status": "active",
"lastRunAt": "2026-07-23T12:00:00Z",
"nextRunAt": "2026-07-23T12:00:00Z",
"createdBy": "string",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
}
POST/api/v1/agent/scheduled-tasks

Create agent scheduled task

https://api-test.orderly-hub.com/api/v1/agent/scheduled-tasks

Update agent scheduled task​

PATCH/api/v1/agent/scheduled-tasks/{id}

Update a scheduled task. Re-registers the schedule if cron or prompt changed.

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Request body​

FieldTypeDescription
namestring
descriptionstring
promptstring
cronExpressionstring
timezonestring
{
"name": "Jane Doe",
"description": "string",
"prompt": "string",
"cronExpression": "string",
"timezone": "string"
}

Responses​

200 Scheduled task updated

AgentScheduledTask object:

FieldTypeDescription
idstring
namestring
descriptionstring
promptstringNatural language prompt executed on schedule
cronExpressionstring
timezonestring
statusactive | paused
lastRunAtstring
nextRunAtstring
createdBystring
createdAtstring
updatedAtstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Jane Doe",
"description": "string",
"prompt": "string",
"cronExpression": "string",
"timezone": "string",
"status": "active",
"lastRunAt": "2026-07-23T12:00:00Z",
"nextRunAt": "2026-07-23T12:00:00Z",
"createdBy": "string",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
}

404 Scheduled task not found

PATCH/api/v1/agent/scheduled-tasks/{id}

Update agent scheduled task

https://api-test.orderly-hub.com/api/v1/agent/scheduled-tasks/

Delete agent scheduled task​

DELETE/api/v1/agent/scheduled-tasks/{id}

Delete a scheduled task and its associated schedule.

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Responses​

200 Scheduled task deleted

Response fields:

FieldTypeDescription
successboolean
{
"success": true
}

404 Scheduled task not found

DELETE/api/v1/agent/scheduled-tasks/{id}

Delete agent scheduled task

https://api-test.orderly-hub.com/api/v1/agent/scheduled-tasks/

Pause a scheduled task​

POST/api/v1/agent/scheduled-tasks/{id}/pause

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Responses​

200 Scheduled task paused

AgentScheduledTask object:

FieldTypeDescription
idstring
namestring
descriptionstring
promptstringNatural language prompt executed on schedule
cronExpressionstring
timezonestring
statusactive | paused
lastRunAtstring
nextRunAtstring
createdBystring
createdAtstring
updatedAtstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Jane Doe",
"description": "string",
"prompt": "string",
"cronExpression": "string",
"timezone": "string",
"status": "active",
"lastRunAt": "2026-07-23T12:00:00Z",
"nextRunAt": "2026-07-23T12:00:00Z",
"createdBy": "string",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
}
POST/api/v1/agent/scheduled-tasks/{id}/pause

Pause a scheduled task

https://api-test.orderly-hub.com/api/v1/agent/scheduled-tasks//pause

Resume a paused scheduled task​

POST/api/v1/agent/scheduled-tasks/{id}/resume

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Responses​

200 Scheduled task resumed

AgentScheduledTask object:

FieldTypeDescription
idstring
namestring
descriptionstring
promptstringNatural language prompt executed on schedule
cronExpressionstring
timezonestring
statusactive | paused
lastRunAtstring
nextRunAtstring
createdBystring
createdAtstring
updatedAtstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Jane Doe",
"description": "string",
"prompt": "string",
"cronExpression": "string",
"timezone": "string",
"status": "active",
"lastRunAt": "2026-07-23T12:00:00Z",
"nextRunAt": "2026-07-23T12:00:00Z",
"createdBy": "string",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
}
POST/api/v1/agent/scheduled-tasks/{id}/resume

Resume a paused scheduled task

https://api-test.orderly-hub.com/api/v1/agent/scheduled-tasks//resume

List standing orders​

GET/api/v1/agent/standing-orders

List automated agent instructions that run on triggers.

Responses​

200 Standing orders

StandingOrder[] object:

FieldTypeDescription
idstring
namestring
descriptionstring
naturalLanguagestringThe instruction in natural language
triggerTypemanual | order_created | order_updated | shipment_created | schedule
conditionsarray
actionsarray
isActiveboolean
priorityinteger
createdBystring
createdAtstring
updatedAtstring
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Jane Doe",
"description": "string",
"naturalLanguage": "string",
"triggerType": "manual",
"conditions": [
{}
],
"actions": [
{}
],
"isActive": true,
"priority": 0,
"createdBy": "string",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
]
}
GET/api/v1/agent/standing-orders

List standing orders

https://api-test.orderly-hub.com/api/v1/agent/standing-orders

Create a standing order​

POST/api/v1/agent/standing-orders

Create an automated instruction for the agent to follow when triggered.

Request body​

FieldTypeDescription
namestring
descriptionstring
naturalLanguagestring
triggerTypestring
conditionsarray
actionsarray
priorityinteger
{
"name": "Jane Doe",
"description": "string",
"naturalLanguage": "string",
"triggerType": "string",
"conditions": [
{}
],
"actions": [
{}
],
"priority": 0
}

Responses​

201 Standing order created

StandingOrder object:

FieldTypeDescription
idstring
namestring
descriptionstring
naturalLanguagestringThe instruction in natural language
triggerTypemanual | order_created | order_updated | shipment_created | schedule
conditionsarray
actionsarray
isActiveboolean
priorityinteger
createdBystring
createdAtstring
updatedAtstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Jane Doe",
"description": "string",
"naturalLanguage": "string",
"triggerType": "manual",
"conditions": [
{}
],
"actions": [
{}
],
"isActive": true,
"priority": 0,
"createdBy": "string",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
}
POST/api/v1/agent/standing-orders

Create a standing order

https://api-test.orderly-hub.com/api/v1/agent/standing-orders

Update a standing order​

PATCH/api/v1/agent/standing-orders/{id}

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Request body​

FieldTypeDescription
namestring
descriptionstring
naturalLanguagestring
triggerTypestring
conditionsarray
actionsarray
isActiveboolean
priorityinteger
{
"name": "Jane Doe",
"description": "string",
"naturalLanguage": "string",
"triggerType": "string",
"conditions": [
{}
],
"actions": [
{}
],
"isActive": true,
"priority": 0
}

Responses​

200 Standing order updated

StandingOrder object:

FieldTypeDescription
idstring
namestring
descriptionstring
naturalLanguagestringThe instruction in natural language
triggerTypemanual | order_created | order_updated | shipment_created | schedule
conditionsarray
actionsarray
isActiveboolean
priorityinteger
createdBystring
createdAtstring
updatedAtstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Jane Doe",
"description": "string",
"naturalLanguage": "string",
"triggerType": "manual",
"conditions": [
{}
],
"actions": [
{}
],
"isActive": true,
"priority": 0,
"createdBy": "string",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
}
PATCH/api/v1/agent/standing-orders/{id}

Update a standing order

https://api-test.orderly-hub.com/api/v1/agent/standing-orders/

Delete a standing order​

DELETE/api/v1/agent/standing-orders/{id}

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Responses​

200 Standing order deleted

Response fields:

FieldTypeDescription
successboolean
{
"success": true
}
DELETE/api/v1/agent/standing-orders/{id}

Delete a standing order

https://api-test.orderly-hub.com/api/v1/agent/standing-orders/

List tool permissions​

GET/api/v1/agent/tool-permissions

View permission configuration for all agent tools.

Responses​

200 Tool permissions

ToolPermission[] object:

FieldTypeDescription
idstring
toolNamestring
approvalRequiredboolean
maxAutoItemsinteger
maxDailyAutoExecutionsinteger
maxOrderValuenumber
riskThresholdnumber
budgetCapDailynumber
updatedBystring
createdAtstring
updatedAtstring
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"toolName": "string",
"approvalRequired": true,
"maxAutoItems": 0,
"maxDailyAutoExecutions": 0,
"maxOrderValue": 0,
"riskThreshold": 0,
"budgetCapDaily": 0,
"updatedBy": "2026-07-23T12:00:00Z",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
]
}
GET/api/v1/agent/tool-permissions

List tool permissions

https://api-test.orderly-hub.com/api/v1/agent/tool-permissions

Update tool permissions​

PATCH/api/v1/agent/tool-permissions

Configure approval requirements and thresholds for agent tools. Requires agent:admin scope.

Request body​

FieldTypeDescription
permissionsarray
{
"permissions": [
{
"toolName": "string",
"approvalRequired": true,
"maxAutoItems": 0,
"maxDailyAutoExecutions": 0,
"maxOrderValue": 0,
"riskThreshold": 0,
"budgetCapDaily": 0
}
]
}

Responses​

200 Permissions updated

ToolPermission[] object:

FieldTypeDescription
idstring
toolNamestring
approvalRequiredboolean
maxAutoItemsinteger
maxDailyAutoExecutionsinteger
maxOrderValuenumber
riskThresholdnumber
budgetCapDailynumber
updatedBystring
createdAtstring
updatedAtstring
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"toolName": "string",
"approvalRequired": true,
"maxAutoItems": 0,
"maxDailyAutoExecutions": 0,
"maxOrderValue": 0,
"riskThreshold": 0,
"budgetCapDaily": 0,
"updatedBy": "2026-07-23T12:00:00Z",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
]
}
PATCH/api/v1/agent/tool-permissions

Update tool permissions

https://api-test.orderly-hub.com/api/v1/agent/tool-permissions