Threads API¶

Use this API to create threads that are used to interact with Cortex Agents.

Create thread¶

POST /api/v2/cortex/threads

Creates a new thread and returns the thread UUID.

请求¶

请求标头¶

标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅身份验证。
`Content-Type`	（必需）应用程序/json

请求正文¶

The request body can include the following field:

字段	类型	描述
`origin_application`	字符串	(Optional) Name of the application that created the thread. Allows grouping threads by application. Limited to 16 bytes.

示例：

{
  "origin_application": "my_app"
}

Copy

响应¶

Returns the thread UUID as a string.

"1234567890"

Copy

Describe thread¶

GET /api/v2/cortex/threads/{id}

Describes a thread and returns a batch of messages in that thread, based on the page_size and the last_message_id, in descending order of creation. This request is only successful if the thread ID belongs to the user.

请求¶

路径参数¶

参数	类型	描述
`id`	整数	(Required) UUID for the thread.

查询参数¶

参数	类型	描述
`page_size`	整数	(Optional) Number of messages to return (default: 20, max: 100).
`last_message_id`	整数	(Optional) The ID of the last message received. Used to set the offset for next batch. Can be empty for the first batch of messages.

请求标头¶

标头	描述
`Authorization`	(Required) Authorization token.
`Content-Type`	（必需）应用程序/json

响应¶

Returns a thread metadata object and an array of messages.

字段	类型	描述
元数据	对象	Metadata for the thread, including the name, application that created the thread, and the time that it was created.
`messages`	数组	Array of message objects.

元数据¶

字段	类型	描述
`thread_id`	整数	UUID for the thread.
`thread_name`	字符串	Name of the thread.
`origin_application`	字符串	The name of the application that created the thread.
`created_on`	整数	Time when the thread was created (milliseconds since UNIX epoch).
`updated_on`	整数	Time when the thread was last updated (milliseconds since UNIX epoch). An update includes adding any new messages to the thread.

消息¶

字段	类型	描述
`message_id`	整数	UUID for the message.
`parent_id`	整数	UUID for the parent message.
`created_on`	整数	Time when the message was created (milliseconds since UNIX epoch).
`role`	字符串	The role that generated this message.
`message_payload`	字符串	Message payload.
`request_id`	字符串	Request ID for the original message.

示例：

{
  "metadata": {
    "thread_id": 1234567890,
    "thread_name": "Support Chat",
    "origin_application": "my_app",
    "created_on": 1717000000000,
    "updated_on": 1717000100000
  },
  "messages": [
    {
      "message_id": 1,
      "parent_id": null,
      "created_on": 1717000000000,
      "role": "user",
      "message_payload": "Hello, I need help.",
      "request_id": "req_001"
    },
    {
      "message_id": 2,
      "parent_id": 1,
      "created_on": 1717000001000,
      "role": "assistant",
      "message_payload": "How can I assist you?",
      "request_id": "req_002"
    }
  ]
}

Copy

Update thread¶

POST /api/v2/cortex/threads/{id}

Updates a thread.

请求¶

路径参数¶

参数	类型	描述
`id`	整数	(Required) UUID for the thread.

请求标头¶

标头	描述
`Authorization`	(Required) Authorization token.
`Content-Type`	（必需）应用程序/json

请求正文¶

字段	类型	描述
`thread_name`	字符串	(Optional) Name of the thread.

示例：

{
  "thread_name": "New Thread Name"
}

Copy

响应¶

Returns the status of the thread update.

{"status": "Thread xxxx successfully updated."}

Copy

List threads¶

GET /api/v2/cortex/threads

Lists all threads belonging to the user.

请求¶

查询参数¶

参数	类型	描述
`origin_application`	字符串	(Optional) Filter the list of threads by this origin application. Without specifying this field, all threads are returned.

请求标头¶

标头	描述
`Authorization`	(Required) Authorization token.
`Content-Type`	（必需）应用程序/json

响应¶

Returns an array of thread metadata objects.

Thread metadata¶

字段	类型	描述
`thread_id`	整数	UUID for the thread.
`thread_name`	字符串	Name of the thread.
`origin_application`	字符串	The name of the application that created the thread.
`created_on`	整数	Time when the thread was created (milliseconds since UNIX epoch).
`updated_on`	整数	Time when the thread was last updated (milliseconds since UNIX epoch). An update includes adding any new messages to the thread.

示例：

[
  {
    "thread_id": 1234567890,
    "thread_name": "Support Chat",
    "origin_application": "my_app",
    "created_on": 1717000000000,
    "updated_on": 1717000100000
  }
]

Copy

Delete thread¶

DELETE /api/v2/cortex/threads/{id}

Deletes a thread and all the messages in that thread.

请求¶

路径参数¶

参数	类型	描述
`id`	整数	(Required) UUID for the thread.

请求标头¶

标头	描述
`Authorization`	(Required) Authorization token.
`Content-Type`	（必需）应用程序/json

响应¶

Returns a success response if the thread is deleted.

{
  "success": true
}

Copy