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

Field	Type	Description
message	string	Natural language message (max 10,000 chars)
conversationId	string	Continue an existing conversation
context	object	Optional 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:

Field	Type	Description
conversationId	string
status	queued | 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

API key (Bearer token)

Request body (JSON){ "message": "string", "conversationId": "550e8400-e29b-41d4-a716-446655440000", "context": { "operationId": "550e8400-e29b-41d4-a716-446655440000", "orderIds": [ "string" ] } }

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

List agent conversations

GET/api/v1/agent/conversations

Parameters

Name	In	Required	Type	Description
page	query	no	integer
limit	query	no	integer

Responses

200 Paginated conversation list

AgentConversation[] object:

Field	Type	Description
id	string
title	string
status	active | archived
messageCount	integer
messages	AgentMessage[]
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

page (query)

limit (query)

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

Get conversation with messages and tool calls

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

Parameters

Name	In	Required	Type	Description
id	path	yes	string

Responses

200 Conversation details with messages

AgentConversation object:

Field	Type	Description
id	string
title	string
status	active | archived
messageCount	integer
messages	AgentMessage[]
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

id * (path)

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

Archive a conversation (soft delete)

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

Parameters

Name	In	Required	Type	Description
id	path	yes	string

Responses

200 Conversation archived

Response fields:

Field	Type	Description
success	boolean

{
  "success": true
}

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

Archive a conversation (soft delete)

API key (Bearer token)

id * (path)

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

Name	In	Required	Type	Description
category	query	no	string	Filter by memory category
scope_type	query	no	string	Filter by scope type

Responses

200 Memory entries

AgentMemory[] object:

Field	Type	Description
id	string
key	string
value	string
category	string
scopeType	string
expiresAt	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

category (query)

scope_type (query)

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

Delete a memory entry

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

Parameters

Name	In	Required	Type	Description
id	path	yes	string

Responses

200 Memory entry deleted

Response fields:

Field	Type	Description
success	boolean

{
  "success": true
}

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

Delete a memory entry

API key (Bearer token)

id * (path)

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

Name	In	Required	Type	Description
status	query	no	pending | approved | rejected | expired | all	Filter by status (default pending)

Responses

200 Pending actions

PendingAction[] object:

Field	Type	Description
id	string
conversationId	string
toolName	string
toolInput	object
status	pending | approved | rejected | expired
reviewedBy	string
reviewedAt	string
reviewNote	string
expiresAt	string
createdAt	string

{
  "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

API key (Bearer token)

status (query)

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

Name	In	Required	Type	Description
id	path	yes	string

Request body

Field	Type	Description
note	string	Optional approval note

{
  "note": "string"
}

Responses

200 Action approved and executed

Response fields:

Field	Type	Description
id	string
status	string
message	string

{
  "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

API key (Bearer token)

id * (path)

Request body (JSON){ "note": "string" }

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

Name	In	Required	Type	Description
id	path	yes	string

Request body

Field	Type	Description
note	string	Optional rejection reason

{
  "note": "string"
}

Responses

200 Action rejected

Response fields:

Field	Type	Description
id	string
status	string

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending"
  }
}

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

Reject a pending action

API key (Bearer token)

id * (path)

Request body (JSON){ "note": "string" }

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:

Field	Type	Description
id	string
name	string
description	string
prompt	string	Natural language prompt executed on schedule
cronExpression	string
timezone	string
status	active | paused
lastRunAt	string
nextRunAt	string
createdBy	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

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

Field	Type	Description
name	string
description	string
prompt	string	Natural language prompt the agent executes on schedule
cronExpression	string	Cron expression (e.g. "0 9 * * 1-5")
timezone	string

{
  "name": "Jane Doe",
  "description": "string",
  "prompt": "string",
  "cronExpression": "string",
  "timezone": "string"
}

Responses

201 Scheduled task created

AgentScheduledTask object:

Field	Type	Description
id	string
name	string
description	string
prompt	string	Natural language prompt executed on schedule
cronExpression	string
timezone	string
status	active | paused
lastRunAt	string
nextRunAt	string
createdBy	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

Request body (JSON){ "name": "Jane Doe", "description": "string", "prompt": "string", "cronExpression": "string", "timezone": "string" }

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

Name	In	Required	Type	Description
id	path	yes	string

Request body

Field	Type	Description
name	string
description	string
prompt	string
cronExpression	string
timezone	string

{
  "name": "Jane Doe",
  "description": "string",
  "prompt": "string",
  "cronExpression": "string",
  "timezone": "string"
}

Responses

200 Scheduled task updated

AgentScheduledTask object:

Field	Type	Description
id	string
name	string
description	string
prompt	string	Natural language prompt executed on schedule
cronExpression	string
timezone	string
status	active | paused
lastRunAt	string
nextRunAt	string
createdBy	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

id * (path)

Request body (JSON){ "name": "Jane Doe", "description": "string", "prompt": "string", "cronExpression": "string", "timezone": "string" }

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

Name	In	Required	Type	Description
id	path	yes	string

Responses

200 Scheduled task deleted

Response fields:

Field	Type	Description
success	boolean

{
  "success": true
}

404 Scheduled task not found

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

Delete agent scheduled task

API key (Bearer token)

id * (path)

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

Pause a scheduled task

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

Parameters

Name	In	Required	Type	Description
id	path	yes	string

Responses

200 Scheduled task paused

AgentScheduledTask object:

Field	Type	Description
id	string
name	string
description	string
prompt	string	Natural language prompt executed on schedule
cronExpression	string
timezone	string
status	active | paused
lastRunAt	string
nextRunAt	string
createdBy	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

id * (path)

Request body (JSON)

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

Name	In	Required	Type	Description
id	path	yes	string

Responses

200 Scheduled task resumed

AgentScheduledTask object:

Field	Type	Description
id	string
name	string
description	string
prompt	string	Natural language prompt executed on schedule
cronExpression	string
timezone	string
status	active | paused
lastRunAt	string
nextRunAt	string
createdBy	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

id * (path)

Request body (JSON)

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:

Field	Type	Description
id	string
name	string
description	string
naturalLanguage	string	The instruction in natural language
triggerType	manual | order_created | order_updated | shipment_created | schedule
conditions	array
actions	array
isActive	boolean
priority	integer
createdBy	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

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

Field	Type	Description
name	string
description	string
naturalLanguage	string
triggerType	string
conditions	array
actions	array
priority	integer

{
  "name": "Jane Doe",
  "description": "string",
  "naturalLanguage": "string",
  "triggerType": "string",
  "conditions": [
    {}
  ],
  "actions": [
    {}
  ],
  "priority": 0
}

Responses

201 Standing order created

StandingOrder object:

Field	Type	Description
id	string
name	string
description	string
naturalLanguage	string	The instruction in natural language
triggerType	manual | order_created | order_updated | shipment_created | schedule
conditions	array
actions	array
isActive	boolean
priority	integer
createdBy	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

Request body (JSON){ "name": "Jane Doe", "description": "string", "naturalLanguage": "string", "triggerType": "string", "conditions": [ {} ], "actions": [ {} ], "priority": 0 }

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

Update a standing order

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

Parameters

Name	In	Required	Type	Description
id	path	yes	string

Request body

Field	Type	Description
name	string
description	string
naturalLanguage	string
triggerType	string
conditions	array
actions	array
isActive	boolean
priority	integer

{
  "name": "Jane Doe",
  "description": "string",
  "naturalLanguage": "string",
  "triggerType": "string",
  "conditions": [
    {}
  ],
  "actions": [
    {}
  ],
  "isActive": true,
  "priority": 0
}

Responses

200 Standing order updated

StandingOrder object:

Field	Type	Description
id	string
name	string
description	string
naturalLanguage	string	The instruction in natural language
triggerType	manual | order_created | order_updated | shipment_created | schedule
conditions	array
actions	array
isActive	boolean
priority	integer
createdBy	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

id * (path)

Request body (JSON){ "name": "Jane Doe", "description": "string", "naturalLanguage": "string", "triggerType": "string", "conditions": [ {} ], "actions": [ {} ], "isActive": true, "priority": 0 }

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

Delete a standing order

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

Parameters

Name	In	Required	Type	Description
id	path	yes	string

Responses

200 Standing order deleted

Response fields:

Field	Type	Description
success	boolean

{
  "success": true
}

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

Delete a standing order

API key (Bearer token)

id * (path)

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:

Field	Type	Description
id	string
toolName	string
approvalRequired	boolean
maxAutoItems	integer
maxDailyAutoExecutions	integer
maxOrderValue	number
riskThreshold	number
budgetCapDaily	number
updatedBy	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

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

Field	Type	Description
permissions	array

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

Responses

200 Permissions updated

ToolPermission[] object:

Field	Type	Description
id	string
toolName	string
approvalRequired	boolean
maxAutoItems	integer
maxDailyAutoExecutions	integer
maxOrderValue	number
riskThreshold	number
budgetCapDaily	number
updatedBy	string
createdAt	string
updatedAt	string

{
  "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

API key (Bearer token)

Request body (JSON){ "permissions": [ { "toolName": "string", "approvalRequired": true, "maxAutoItems": 0, "maxDailyAutoExecutions": 0, "maxOrderValue": 0, "riskThreshold": 0, "budgetCapDaily": 0 } ] }

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