# Create, delete, and retrieve threads (/en/api-reference/api-ref/im/thread-management/create-delete-retrieve-threads)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

This page shows how to create, modify, delete, and retrieve a thread by calling Chat RESTful APIs. Before calling the following methods, ensure that you understand the call frequency limit described in [Limitations](../limitations#call-limit-of-server-sides).

## Common parameters [#common-parameters]

The following table lists common request and response parameters of the Chat RESTful APIs:

### Request parameters [#request-parameters]

| Parameter | Type   | Description                                                                                                                                                                                                                             | Required |
| :-------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `host`    | String | The domain name assigned by the Chat service to access RESTful APIs. For how to get the domain name, see [Get the information of your project](/en/realtime-media/im/get-started/enable#get-the-information-of-the-agora-chat-project). | Yes      |
| `app_id`  | String | The unique identifier automatically assigned to each project by Agora                                                                                                                                                                   | Yes      |

### Response parameters [#response-parameters]

| Parameter         | Type   | Description                                                                                          |
| :---------------- | :----- | :--------------------------------------------------------------------------------------------------- |
| `action`          | String | The request method.                                                                                  |
| `organization`    | String | The unique identifier assigned to each company (organization) by the Chat service.                   |
| `application`     | String | A unique internal ID assigned to each app by the Chat service. You can safely ignore this parameter. |
| `applicationName` | String | The unique identifier assigned to each app by the Chat service.                                      |
| `data`            | JSON   | The details of the response.                                                                         |
| `timestamp`       | Number | The Unix timestamp (ms) of the HTTP response.                                                        |
| `duration`        | Number | The duration (ms) from when the HTTP request is sent to the time the response is received.           |
| `uri`             | String | The request URI.                                                                                     |
| `path`            | String | The request path, which is part of the request URI. You can safely ignore this parameter.            |
| `entities `       | JSON   | The response entity.                                                                                 |
| `properties`      | String | The request property.                                                                                |

## Authorization [#authorization]

Chat RESTful APIs require Bearer HTTP authentication. Every time an HTTP request is sent, the following `Authorization` field must be filled in the request header:

```html
Authorization: Bearer ${YourAppToken}
```

In order to improve the security of the project, Agora uses a token (dynamic key) to authenticate users before they log in to the chat system. Chat RESTful APIs only support authenticating users using app tokens. For details, see [Authentication using App Token](/en/realtime-media/im/build/secure-access-and-authentication/authentication).

## Creating a thread [#creating-a-thread]

Creates a thread. An app can have up to 100,000 threads by default. To increase the limit, contact [support@agora.io](mailto\:support@agora.io).

For each App Key, the call frequency limit of this method is 100 per second.

### HTTP request [#http-request]

```html
POST https://{host}/app-id/{app_id}/thread
```

#### Path parameter [#path-parameter]

For the descriptions of the path parameters, see [Common Parameters](#request).

#### Request header [#request-header]

For the descriptions of the request headers, see [Authorization](#auth).

#### Request body [#request-body]

| Parameter  | Type   | Description                                                                     | Required |
| :--------- | :----- | :------------------------------------------------------------------------------ | :------- |
| `group_id` | String | The ID of the group to which the thread belongs.                                | Yes      |
| `name`     | String | The name of the thread. The maximum length of the thread name is 64 characters. | Yes      |
| `msg_id`   | String | The ID of the message based on which the thread is created.                     | Yes      |
| `owner`    | String | The username of the thread creator.                                             | Yes      |

### HTTP response [#http-response]

#### Response body [#response-body]

If the returned HTTP status code is `200`, the request succeeds, and the data field in the response body contains the following parameters:

| Parameter   | Type   | Description           |
| :---------- | :----- | :-------------------- |
| `thread_id` | String | The ID of the thread. |

For other fields and descriptions, see [Common parameters](#response).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](#Status-codes) for possible causes.

### Example [#example]

#### Request example [#request-example]

```bash
curl -X POST http://XXXX.com/XXXX/testapp/thread -H 'Authorization: Bearer ' -H 'Content-Type:application/json' -d '
{
    "group_id": 179800091197441,
    "name": "1",
    "owner": "test4",
    "msg_id": 1234
}'
```

#### Response example [#response-example]

```json
{
    "action": "post",
    "applicationName": "testapp",
    "duration": 4,
    "data": {
        "thread_id": "177916702949377"
    },
    "organization": "XXXX",
    "timestamp": 1650869972109,
    "uri": "http://XXXX.com/XXXX/testy/thread"
}
```

## Modifying a thread [#modifying-a-thread]

Changes the name of the specified thread.

For each App Key, the call frequency limit of this method is 100 per second.

### HTTP request [#http-request-1]

```html
PUT https://{host}/app-id/{app_id}/thread/{thread_id}
```

#### Path parameter [#path-parameter-1]

| Parameter   | Type   | Description           | Required |
| :---------- | :----- | :-------------------- | :------- |
| `thread_id` | String | The ID of the thread. | Yes      |

For the descriptions of the other path parameters, see [Common Parameters](#request).

#### Request header [#request-header-1]

For the descriptions of the request headers, see [Authorization](#auth).

#### Request body [#request-body-1]

| Parameter | Type   | Description                                                                             | Required |
| :-------- | :----- | :-------------------------------------------------------------------------------------- | :------- |
| `name`    | String | The updated name of the thread. The maximum length of the thread name is 64 characters. | Yes      |

### HTTP response [#http-response-1]

#### Response body [#response-body-1]

If the returned HTTP status code is `200`, the request succeeds, and the data field in the response body contains the following parameters:

| Parameter | Type   | Description                     |
| :-------- | :----- | :------------------------------ |
| `name`    | String | The updated name of the thread. |

For other fields and descriptions, see [Common parameters](#response).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](#Status-codes) for possible causes.

### Example [#example-1]

#### Request example [#request-example-1]

```bash
curl -X PUT http://XXXX.com/XXXX/testapp/thread/177916702949377 -H 'Authorization: Bearer ' -d '{"name": "test4"}'
```

#### Response example [#response-example-1]

```json
{
    "action": "put",
    "applicationName": "testapp",
    "duration": 4,
    "data": {
        "name": "test4"
    },
    "organization": "XXXX",
    "timestamp": 1650869972109,
    "uri": "http://XXXX.com/XXXX/testy/thread"
}
```

## Deleting a thread [#deleting-a-thread]

Deletes the specified thread.

### HTTP request [#http-request-2]

```html
DELETE https://{host}/app-id/{app_id}/thread/{thread_id}
```

#### Path parameter [#path-parameter-2]

| Parameter   | Type   | Description           | Required |
| :---------- | :----- | :-------------------- | :------- |
| `thread_id` | String | The ID of the thread. | Yes      |

For the descriptions of the other path parameters, see [Common Parameters](#request).

#### Request header [#request-header-2]

For the descriptions of the request headers, see [Authorization](#auth).

### HTTP response [#http-response-2]

#### Response body [#response-body-2]

If the returned HTTP status code is `200`, the request succeeds, and the data field in the response body contains the following parameters:

| Parameter | Type   | Description                                                               |
| :-------- | :----- | :------------------------------------------------------------------------ |
| `status`  | String | Whether the thread is deleted. `ok` indicates that the thread is deleted. |

For other fields and descriptions, see [Common parameters](#response).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](#Status-codes) for possible causes.

### Example [#example-2]

#### Request example [#request-example-2]

```bash
curl -X DELETE http://XXXX.com/XXXX/testapp/thread/177916702949377 -H 'Authorization: Bearer '
```

#### Response example [#response-example-2]

```json
{
    "action": "delete",
    "applicationName": "testapp",
    "duration": 4,
    "data": {
        "status": "ok"
    },
    "organization": "XXXX",
    "timestamp": 1650869972109,
    "uri": "http://XXXX.com/XXXX/testy/thread"
}
```

## Retrieving all the threads under the app [#retrieving-all-the-threads-under-the-app]

Retrieves all the threads under the app.

For each App Key, the call frequency limit of this method is 100 per second.

### HTTP request [#http-request-3]

```html
GET https://{host}/app-id/{app_id}/thread?limit={limit}&cursor={cursor}&sort={sort}
```

#### Path parameter [#path-parameter-3]

| Parameter | Type   | Description                                                                                                                                                          | Required |
| :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `limit`   | String | The maximum number of threads to retrieve per page. The range is \[1, 50]. The default value is 50.                                                                  | No       |
| `cursor`  | String | The page from which to start retrieving threads. Pass in `null` or an empty string at the first query.                                                               | No       |
| `sort`    | String | The order in which to list the query results: `asc`: In chronological order of thread creation. (Default) `desc`: In reverse chronological order of thread creation. | No       |

For the descriptions of the other path parameters, see [Common Parameters](#request).

#### Request header [#request-header-3]

For the descriptions of the request headers, see [Authorization](#auth).

### HTTP response [#http-response-3]

#### Response body [#response-body-3]

If the returned HTTP status code is `200`, the request succeeds, and the entity field in the response body contains the following parameters:

| Parameter           | Type   | Description                                                        |
| :------------------ | :----- | :----------------------------------------------------------------- |
| `id`                | String | The ID of the thread.                                              |
| `properties.cursor` | String | The cursor that indicates the starting position of the next query. |

For other fields and descriptions, see [Common parameters](#response).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](#Status-codes) for possible causes.

### Example [#example-3]

#### Request example [#request-example-3]

```json
curl -X GET http://XXXX.com/XXXX/testapp/thread -H 'Authorization: Bearer '
```

#### Response example [#response-example-3]

```json
{
    "action": "get",
    "applicationName": "testapp",
    "duration": 7,
    "entities": [
        {
            "id": "179786360094768"
        }
    ],
    "organization": "XXXX",
    "properties": {
        "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aW06dGhyZWFkOmVhc2Vtb2ItZGVtbyN0ZXN0eToxNzk3ODYzNjExNDMzMTE"
    },
    "timestamp": 1650869750247,
    "uri": "http://XXXX.com/XXXX/testy/thread"
}
```

## Retrieving all the threads a user joins under the app [#retrieving-all-the-threads-a-user-joins-under-the-app]

Retrieves all the threads a user joins under the app.

For each App Key, the call frequency limit of this method is 100 per second.

### HTTP request [#http-request-4]

```html
GET https://{host}/app-id/{app_id}/threads/user/{username}?limit={limit}&cursor={cursor}&sort={sort}
```

#### Path parameter [#path-parameter-4]

For the descriptions of the path parameters, see [Common Parameters](#request).

#### Query parameter [#query-parameter]

| Parameter | Type   | Description                                                                                                                                                          | Required |
| :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `limit`   | String | The maximum number of threads to retrieve per page. The range is \[1, 50]. The default value is 50.                                                                  | No       |
| `cursor`  | String | The page from which to start retrieving threads. Pass in `null` or an empty string at the first query.                                                               | No       |
| `sort`    | String | The order in which to list the query results: `asc`: In chronological order of thread creation. (Default) `desc`: In reverse chronological order of thread creation. | No       |

For the descriptions of the other path parameters, see [Common Parameters](#request).

#### Request header [#request-header-4]

For the descriptions of the request headers, see [Authorization](#auth).

### HTTP response [#http-response-4]

#### Response body [#response-body-4]

If the returned HTTP status code is `200`, the request succeeds, and the entity field in the response body contains the following parameters:

| Parameter           | Type   | Description                                                        |
| :------------------ | :----- | :----------------------------------------------------------------- |
| `name`              | String | The thread name.                                                   |
| `owner`             | String | The thread creator.                                                |
| `id`                | String | The thread ID.                                                     |
| `msgId`             | String | The ID of the message based on which the thread is created.        |
| `groupId`           | String | The ID of the group to which the thread belongs.                   |
| `created`           | String | The Unix timestamp when the thread is created.                     |
| `properties.cursor` | String | The cursor that indicates the starting position of the next query. |

For other fields and descriptions, see [Common parameters](#response).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](#Status-codes) for possible causes.

### Example [#example-4]

#### Request example [#request-example-4]

```bash
curl -X GET http://XXXX.com/XXXX/testapp/threads/user/test4 -H 'Authorization: Bearer '
```

#### Response example [#response-example-4]

```json
{
    "action": "get",
    "applicationName": "testapp",
    "duration": 4,
    "entities": [
        {
            "name": "1",
            "owner": "test4",
            "id": "17XXXX69",
            "msgId": "1920",
            "groupId": "17XXXX61",
            "created": 1650856033420
        }
    ],
    "organization": "XXXX",
    "properties": {
        "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aW06dGhyZWFkOmVhc2Vtb2ItZGVtbyN0ZXN0eToxNzk3ODYzNjAwOTQ3Nzg"
    },
    "timestamp": 1650869972109,
    "uri": "http://XXXX.com/XXXX/testy/threads/user/test4"
}
```

## Retrieving all the threads a user joins under a group [#retrieving-all-the-threads-a-user-joins-under-a-group]

Retrieves all the threads a user joins under a group.

For each App Key, the call frequency limit of this method is 100 per second.

### HTTP request [#http-request-5]

```html
GET https://{host}/app-id/{app_id}/threads/chatgroups/{group_id}/user/{username}?limit={limit}&cursor={cursor}&sort={sort}
```

#### Path parameter [#path-parameter-5]

| Parameter  | Type   | Description                           | Required |
| :--------- | :----- | :------------------------------------ | :------- |
| `group_id` | String | The ID of the group.                  | Yes      |
| `username` | String | The unique login account of the user. | Yes      |

For the descriptions of the other path parameters, see [Common Parameters](#request).

#### Query parameter [#query-parameter-1]

| Parameter | Type   | Description                                                                                                                                                          | Required |
| :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `limit`   | String | The maximum number of threads to retrieve per page. The range is \[1, 50]. The default value is 50.                                                                  | No       |
| `cursor`  | String | The page from which to start retrieving threads. Pass in `null` or an empty string at the first query.                                                               | No       |
| `sort`    | String | The order in which to list the query results: `asc`: In chronological order of thread creation. (Default) `desc`: In reverse chronological order of thread creation. | No       |

#### Request header [#request-header-5]

For the descriptions of the request headers, see [Authorization](#auth).

### HTTP response [#http-response-5]

#### Response body [#response-body-5]

If the returned HTTP status code is `200`, the request succeeds, and the entity field in the response body contains the following parameters.

For the last page of data, the response still contains `cursor` and the number of retrieved threads is smaller than the value of `limit` in the request. If there is no more thread data returned in the response, you have retrieved data of all threads in this group.

| Parameter | Type   | Description                                                 |
| :-------- | :----- | :---------------------------------------------------------- |
| `name`    | String | The thread name.                                            |
| `owner`   | String | The thread creator.                                         |
| `id`      | String | The thread ID.                                              |
| `msgId`   | String | The ID of the message based on which the thread is created. |
| `groupId` | String | The ID of the group to which the thread belongs.            |
| `created` | String | The Unix timestamp when the thread is created.              |

For other fields and descriptions, see [Common parameters](#response).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](#Status-codes) for possible causes.

### Example [#example-5]

#### Request example [#request-example-5]

```bash
curl -X GET http://XXXX.com/XXXX/testapp/threads/user/test4 -H 'Authorization: Bearer '
```

#### Response example [#response-example-5]

```json
{
    "action": "get",
    "applicationName": "testapp",
    "duration": 4,
    "entities": [
        {
            "name": "1",
            "owner": "test4",
            "id": "17XXXX69",
            "msgId": "1920",
            "groupId": "17XXXX61",
            "created": 1650856033420
        }
    ],
    "organization": "XXXX",
    "properties": {
        "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aW06dGhyZWFkOmVhc2Vtb2ItZGVtbyN0ZXN0eToxNzk3ODYzNjAwOTQ3Nzg"
    },
    "timestamp": 1650869972109,
    "uri": "http://XXXX.com/XXXX/testy/threads/user/test4"
}
```

## Status codes [#status-codes]

For details, see [HTTP Status Codes](../http-status-codes).