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.

Send Message

POST/api/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. Messages are associated with a conversation for context continuity.

Request Body

Field	Type	Required	Description
`message`	string	Yes	The user’s message to the agent
`conversation_id`	string	No	Existing conversation ID to continue (creates a new one if omitted)


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

Response


{
  "data": {
    "conversation_id": "uuid",
    "message_id": "uuid",
    "response": "You have 23 orders pending shipment today. 18 are domestic and 5 are international.",
    "actions": [],
    "sources": [
      { "type": "query", "description": "Orders with status=pending, created today" }
    ]
  }
}

When the agent proposes actions, they appear in the actions array:


{
  "data": {
    "conversation_id": "uuid",
    "message_id": "uuid",
    "response": "I can create shipments for all 23 pending orders using FedEx Ground. Would you like me to proceed?",
    "actions": [
      {
        "id": "uuid",
        "type": "create_shipment",
        "status": "pending_approval",
        "description": "Create FedEx Ground shipments for 23 orders",
        "affected_item_count": 23
      }
    ]
  }
}

List Conversations

GET/api/agent/conversations

List all agent conversations.

Requiredagent:read

Returns a paginated list of conversations with the AI agent, including message counts and last activity.

Query Parameters

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


curl -X GET "https://api.orderly.dev/api/agent/conversations" \
  -H "Authorization: Bearer ord_sk_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "title": "Pending shipment inquiry",
      "message_count": 4,
      "last_message_at": "2026-01-15T10:30:00Z",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 12, "totalPages": 1, "hasMore": false }
}

Approve Action

POST/api/agent/actions/:id/approve

Approve a pending agent action for execution.

Requiredagent:write

Approves a pending action proposed by the AI agent. Once approved, the action is executed as an operation.


curl -X POST "https://api.orderly.dev/api/agent/actions/550e8400-e29b-41d4-a716-446655440000/approve" \
  -H "Authorization: Bearer ord_sk_..."

Response


{
  "data": {
    "id": "uuid",
    "status": "approved",
    "operation_id": "uuid",
    "approved_at": "2026-01-15T10:35:00Z"
  }
}

Reject Action

POST/api/agent/actions/:id/reject

Reject a pending agent 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
`reason`	string	No	Reason for rejection (shared with the agent for learning)


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

Response


{
  "data": {
    "id": "uuid",
    "status": "rejected",
    "rejected_at": "2026-01-15T10:35:00Z"
  }
}