Agent

Interact with Orderly’s AI agent for natural-language operations management. The agent can query data, propose actions, and execute approved operations on your behalf.

The agent system includes:

Chat — send messages and receive AI-powered responses
Conversations — manage chat history and context
Pending Actions — review, approve, or reject actions the agent proposes
Tool Permissions — configure which tools require approval and set safety limits
Memory — persistent knowledge the agent uses across conversations
Standing Orders — reusable rules the agent follows automatically
Scheduled Tasks — cron-based tasks the agent runs on a schedule

Chat

Send Message

POST/api/v1/agent/chat

Send a message to the AI agent and receive a response.

Requiredagent:write

Sends a message to the AI agent. The agent processes the message, potentially querying your data or proposing actions, and returns a response. If no conversationId is provided, a new conversation is created automatically.

Messages are limited to 10,000 characters.

Request Body

Field	Type	Required	Description
`message`	string	Yes	The user’s message to the agent (max 10,000 characters)
`conversationId`	string	No	Existing conversation ID to continue (creates a new one if omitted)
`context`	object	No	Additional context for the message
`context.operationId`	string	No	Related operation ID
`context.orderIds`	string[]	No	Related order IDs


curl -X POST "https://api.orderly-hub.com/api/v1/agent/chat" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How many orders are pending shipment today?",
    "conversationId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response


{
  "data": {
    "conversationId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed"
  }
}

Conversations

List Conversations

GET/api/v1/agent/conversations

List all agent conversations for the current organization.

Requiredagent:read

Returns a paginated list of active conversations with the AI agent.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 50)


curl -X GET "https://api.orderly-hub.com/api/v1/agent/conversations?page=1&limit=20" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Pending shipment inquiry",
      "status": "active",
      "message_count": 4,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 12,
    "totalPages": 1
  }
}

Get Conversation

GET/api/v1/agent/conversations/:id

Retrieve a conversation with all its messages and tool calls.

Requiredagent:read

Returns the full conversation object including all messages. Each message includes any associated tool calls the agent made during that turn.


curl -X GET "https://api.orderly-hub.com/api/v1/agent/conversations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Pending shipment inquiry",
    "status": "active",
    "organization_id": "uuid",
    "message_count": 2,
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:30:00Z",
    "messages": [
      {
        "id": "uuid",
        "role": "user",
        "content": "How many orders are pending?",
        "input_tokens": null,
        "output_tokens": null,
        "created_at": "2026-01-15T10:00:00Z",
        "toolCalls": []
      },
      {
        "id": "uuid",
        "role": "assistant",
        "content": "You have 23 orders pending shipment today.",
        "input_tokens": 150,
        "output_tokens": 42,
        "created_at": "2026-01-15T10:00:01Z",
        "toolCalls": [
          {
            "id": "uuid",
            "message_id": "uuid",
            "tool_use_id": "toolu_abc123",
            "tool_name": "count_orders_by_status",
            "tool_input": { "status": "pending" },
            "result_content": "{ \"pending\": 23 }",
            "is_error": false,
            "duration_ms": 120,
            "resolved_via": "auto",
            "created_at": "2026-01-15T10:00:00Z"
          }
        ]
      }
    ]
  }
}

Delete Conversation

DELETE/api/v1/agent/conversations/:id

Archive a conversation (soft delete).

Requiredagent:write

Archives a conversation. Archived conversations no longer appear in the list but are not permanently deleted.


curl -X DELETE "https://api.orderly-hub.com/api/v1/agent/conversations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

Pending Actions

When the agent proposes a write operation (creating shipments, updating orders, etc.), it creates a pending action that must be approved before execution — unless the tool is configured for auto-approval in tool permissions.

List Pending Actions

GET/api/v1/agent/pending-actions

List pending actions awaiting approval.

Requiredagent:read

Returns pending actions for the organization. Defaults to showing only actions with pending status.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `pending` (default), `approved`, `rejected`, `expired`, or `all`


curl -X GET "https://api.orderly-hub.com/api/v1/agent/pending-actions?status=pending" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "uuid",
      "conversation_id": "uuid",
      "tool_name": "create_shipment",
      "tool_input": { "order_ids": ["uuid1", "uuid2"], "carrier": "fedex_ground" },
      "description": "Create FedEx Ground shipments for 2 orders",
      "status": "pending",
      "affected_item_count": 2,
      "idempotency_key": "unique-key",
      "expires_at": "2026-01-15T11:00:00Z",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Approve Pending Action

POST/api/v1/agent/pending-actions/:id/approve

Approve a pending action for execution.

Requiredagent:write

Approves a pending action proposed by the AI agent. Once approved, the action is executed. Returns 410 Gone if the action has expired.

Request Body

Field	Type	Required	Description
`note`	string	No	Optional note to attach to the approval


curl -X POST "https://api.orderly-hub.com/api/v1/agent/pending-actions/550e8400-e29b-41d4-a716-446655440000/approve" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{"note": "Approved for shipping"}'

Response


{
  "status": "approved",
  "action_id": "550e8400-e29b-41d4-a716-446655440000",
  "result": "Action executed successfully"
}

Reject Pending Action

POST/api/v1/agent/pending-actions/:id/reject

Reject a pending action.

Requiredagent:write

Rejects a pending action proposed by the AI agent. The action is cancelled and will not be executed.

Request Body

Field	Type	Required	Description
`note`	string	No	Reason for rejection (shared with the agent for learning)


curl -X POST "https://api.orderly-hub.com/api/v1/agent/pending-actions/550e8400-e29b-41d4-a716-446655440000/reject" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{"note": "Use UPS instead of FedEx for these orders"}'

Response


{
  "status": "rejected",
  "action_id": "550e8400-e29b-41d4-a716-446655440000"
}

Tool Permissions

Configure which agent tools require human approval and set safety limits for auto-execution.

List Tool Permissions

GET/api/v1/agent/tool-permissions

List tool permission configurations.

Requiredagent:read

Returns all tool permission configurations for the organization.


curl -X GET "https://api.orderly-hub.com/api/v1/agent/tool-permissions" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "tool_name": "create_shipment",
      "approval_required": true,
      "max_auto_items": 10,
      "max_daily_auto_executions": 50,
      "max_order_value": 500.00,
      "risk_threshold": 0.5,
      "budget_cap_daily": 1000.00,
      "updated_by": "uuid",
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-01-10T08:00:00Z"
    }
  ]
}

Update Tool Permissions

PATCH/api/v1/agent/tool-permissions

Update tool permission configurations.

Requiredagent:admin

Upserts tool permission configurations. If a permission for the given tool already exists, it is updated; otherwise a new one is created.

Request Body

Field	Type	Required	Description
`permissions`	array	Yes	Array of permission objects
`permissions[].toolName`	string	Yes	Name of the tool
`permissions[].approvalRequired`	boolean	Yes	Whether the tool requires human approval
`permissions[].maxAutoItems`	number	No	Max items per auto-execution (default: 10)
`permissions[].maxDailyAutoExecutions`	number	No	Max auto-executions per day
`permissions[].maxOrderValue`	number	No	Max order value for auto-execution
`permissions[].riskThreshold`	number	No	Risk score threshold for auto-execution (default: 0.5)
`permissions[].budgetCapDaily`	number	No	Daily budget cap for auto-executed actions


curl -X PATCH "https://api.orderly-hub.com/api/v1/agent/tool-permissions" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      {
        "toolName": "create_shipment",
        "approvalRequired": false,
        "maxAutoItems": 5,
        "maxDailyAutoExecutions": 100,
        "maxOrderValue": 200.00,
        "riskThreshold": 0.3,
        "budgetCapDaily": 5000.00
      },
      {
        "toolName": "cancel_order",
        "approvalRequired": true
      }
    ]
  }'

Response


{
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "tool_name": "create_shipment",
      "approval_required": false,
      "max_auto_items": 5,
      "max_daily_auto_executions": 100,
      "max_order_value": 200.00,
      "risk_threshold": 0.3,
      "budget_cap_daily": 5000.00,
      "updated_by": "uuid",
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": "uuid",
      "organization_id": "uuid",
      "tool_name": "cancel_order",
      "approval_required": true,
      "max_auto_items": 10,
      "max_daily_auto_executions": null,
      "max_order_value": null,
      "risk_threshold": 0.5,
      "budget_cap_daily": null,
      "updated_by": "uuid",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Memory

The agent stores and retrieves persistent knowledge entries — preferences, past decisions, and organizational context — to improve responses over time.

List Memory

GET/api/v1/agent/memory

List agent memory entries.

Requiredagent:read

Returns memory entries for the organization. Supports filtering by category and scope type.

Query Parameters

Parameter	Type	Description
`category`	string	Filter by category (e.g., `preference`, `fact`, `decision`)
`scope_type`	string	Filter by scope type (e.g., `organization`, `user`, `bridge`)


curl -X GET "https://api.orderly-hub.com/api/v1/agent/memory?category=preference" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "category": "preference",
      "scope_type": "organization",
      "scope_id": "uuid",
      "content": "Always use FedEx Ground for domestic orders under $50",
      "source": "user_instruction",
      "confidence": 0.95,
      "expires_at": null,
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-01-10T08:00:00Z"
    }
  ]
}

Delete Memory

DELETE/api/v1/agent/memory/:id

Delete a memory entry.

Requiredagent:write

Permanently deletes a memory entry.


curl -X DELETE "https://api.orderly-hub.com/api/v1/agent/memory/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

Standing Orders

Standing orders are reusable rules that tell the agent how to handle specific situations automatically. They are defined in natural language and can include structured conditions and actions.

List Standing Orders

GET/api/v1/agent/standing-orders

List all standing orders.

Requiredagent:read

Returns all standing orders for the organization, sorted by priority (highest first).


curl -X GET "https://api.orderly-hub.com/api/v1/agent/standing-orders" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "name": "Rush shipping for VIP customers",
      "description": "Automatically upgrade shipping for orders from VIP-tagged customers",
      "natural_language": "When a new order comes in from a customer tagged as VIP, use overnight shipping instead of standard ground.",
      "trigger_type": "on_order_created",
      "conditions": [],
      "actions": [],
      "priority": 10,
      "is_active": true,
      "created_by": "uuid",
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-01-10T08:00:00Z"
    }
  ]
}

Create Standing Order

POST/api/v1/agent/standing-orders

Create a new standing order.

Requiredagent:write

Creates a new standing order. The naturalLanguage field is the primary instruction the agent uses; conditions and actions provide optional structured data.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Name of the standing order
`description`	string	No	Human-readable description
`naturalLanguage`	string	Yes	Natural language instruction for the agent
`triggerType`	string	No	When to trigger: `manual` (default), `on_order_created`, `on_shipment_created`, etc.
`conditions`	array	No	Structured conditions (default: `[]`)
`actions`	array	No	Structured actions (default: `[]`)
`priority`	number	No	Priority level, higher = more important (default: 0)


curl -X POST "https://api.orderly-hub.com/api/v1/agent/standing-orders" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rush shipping for VIP customers",
    "description": "Upgrade shipping for VIP-tagged customers",
    "naturalLanguage": "When a new order comes in from a customer tagged as VIP, use overnight shipping instead of standard ground.",
    "triggerType": "on_order_created",
    "priority": 10
  }'

Response (201 Created)


{
  "data": {
    "id": "uuid",
    "organization_id": "uuid",
    "name": "Rush shipping for VIP customers",
    "description": "Upgrade shipping for VIP-tagged customers",
    "natural_language": "When a new order comes in from a customer tagged as VIP, use overnight shipping instead of standard ground.",
    "trigger_type": "on_order_created",
    "conditions": [],
    "actions": [],
    "priority": 10,
    "is_active": true,
    "created_by": "uuid",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  }
}

Update Standing Order

PATCH/api/v1/agent/standing-orders/:id

Update a standing order.

Requiredagent:write

Updates one or more fields on a standing order. Only the fields you include in the request body are changed.

Request Body

Field	Type	Required	Description
`name`	string	No	Updated name
`description`	string	No	Updated description
`naturalLanguage`	string	No	Updated instruction
`triggerType`	string	No	Updated trigger type
`conditions`	array	No	Updated conditions
`actions`	array	No	Updated actions
`isActive`	boolean	No	Enable or disable the standing order
`priority`	number	No	Updated priority


curl -X PATCH "https://api.orderly-hub.com/api/v1/agent/standing-orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false,
    "priority": 5
  }'

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "uuid",
    "name": "Rush shipping for VIP customers",
    "description": "Upgrade shipping for VIP-tagged customers",
    "natural_language": "When a new order comes in from a customer tagged as VIP, use overnight shipping instead of standard ground.",
    "trigger_type": "on_order_created",
    "conditions": [],
    "actions": [],
    "priority": 5,
    "is_active": false,
    "created_by": "uuid",
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  }
}

Delete Standing Order

DELETE/api/v1/agent/standing-orders/:id

Delete a standing order.

Requiredagent:write

Permanently deletes a standing order.


curl -X DELETE "https://api.orderly-hub.com/api/v1/agent/standing-orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

Scheduled Tasks

Scheduled tasks run agent prompts on a cron schedule via QStash. Use them for recurring operations like daily reports, inventory checks, or automated order processing.

List Scheduled Tasks

GET/api/v1/agent/scheduled-tasks

List all scheduled tasks.

Requiredagent:read

Returns all scheduled tasks for the organization.


curl -X GET "https://api.orderly-hub.com/api/v1/agent/scheduled-tasks" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "name": "Daily order summary",
      "description": "Generate a summary of all orders from the past 24 hours",
      "prompt": "Give me a summary of all orders from the last 24 hours, including totals by status and any flagged issues.",
      "cron_expression": "0 9 * * *",
      "timezone": "America/New_York",
      "status": "active",
      "last_run_at": "2026-01-15T14:00:00Z",
      "next_run_at": "2026-01-16T14:00:00Z",
      "created_by": "uuid",
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-01-10T08:00:00Z"
    }
  ]
}

Create Scheduled Task

POST/api/v1/agent/scheduled-tasks

Create a new scheduled task.

Requiredagent:admin

Creates a new scheduled task and registers it with QStash for cron execution.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Name of the task
`description`	string	No	Human-readable description
`prompt`	string	Yes	The message to send to the agent on each run
`cronExpression`	string	Yes	Cron expression for the schedule (e.g., `0 9 * * *` for daily at 9am)
`timezone`	string	No	IANA timezone (e.g., `America/New_York`)


curl -X POST "https://api.orderly-hub.com/api/v1/agent/scheduled-tasks" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily order summary",
    "description": "Generate a summary of all orders from the past 24 hours",
    "prompt": "Give me a summary of all orders from the last 24 hours, including totals by status and any flagged issues.",
    "cronExpression": "0 9 * * *",
    "timezone": "America/New_York"
  }'

Response (201 Created)


{
  "data": {
    "id": "uuid",
    "organization_id": "uuid",
    "name": "Daily order summary",
    "description": "Generate a summary of all orders from the past 24 hours",
    "prompt": "Give me a summary of all orders from the last 24 hours, including totals by status and any flagged issues.",
    "cron_expression": "0 9 * * *",
    "timezone": "America/New_York",
    "status": "active",
    "created_by": "uuid",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  }
}

Update Scheduled Task

PATCH/api/v1/agent/scheduled-tasks/:id

Update a scheduled task.

Requiredagent:admin

Updates a scheduled task. If cronExpression or prompt are changed, the QStash schedule is re-registered.

Request Body

Field	Type	Required	Description
`name`	string	No	Updated name
`description`	string	No	Updated description
`prompt`	string	No	Updated prompt
`cronExpression`	string	No	Updated cron expression
`timezone`	string	No	Updated timezone


curl -X PATCH "https://api.orderly-hub.com/api/v1/agent/scheduled-tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cronExpression": "0 8 * * 1-5",
    "prompt": "Give me a summary of all orders from the last 24 hours. Focus on any delayed shipments."
  }'

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "uuid",
    "name": "Daily order summary",
    "description": "Generate a summary of all orders from the past 24 hours",
    "prompt": "Give me a summary of all orders from the last 24 hours. Focus on any delayed shipments.",
    "cron_expression": "0 8 * * 1-5",
    "timezone": "America/New_York",
    "status": "active",
    "created_by": "uuid",
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  }
}

Delete Scheduled Task

DELETE/api/v1/agent/scheduled-tasks/:id

Delete a scheduled task and its QStash schedule.

Requiredagent:admin

Permanently deletes a scheduled task and removes its cron schedule from QStash.


curl -X DELETE "https://api.orderly-hub.com/api/v1/agent/scheduled-tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

Pause Scheduled Task

POST/api/v1/agent/scheduled-tasks/:id/pause

Pause a scheduled task.

Requiredagent:admin

Pauses a scheduled task. The QStash cron job is suspended and the task will not run until resumed.


curl -X POST "https://api.orderly-hub.com/api/v1/agent/scheduled-tasks/550e8400-e29b-41d4-a716-446655440000/pause" \
  -H "Authorization: Bearer oh_..."

Response


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

Resume Scheduled Task

POST/api/v1/agent/scheduled-tasks/:id/resume

Resume a paused scheduled task.

Requiredagent:admin

Resumes a paused scheduled task. The QStash cron job is reactivated.


curl -X POST "https://api.orderly-hub.com/api/v1/agent/scheduled-tasks/550e8400-e29b-41d4-a716-446655440000/resume" \
  -H "Authorization: Bearer oh_..."

Response


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