Threads

Get threads

1GET https://api.markprompt.com/threads

Retrieves threads in the given time range.

Request body

KeyTypeDescription
fromstring

The start of the range, as an ISO 8601 string.

tostring

The end of the range, as an ISO 8601 string.

limitnumber

The maximum number of results to return. Default: 50.

pagenumber

The page index. Default: 0.

answeredStatus"answered" | "unanswered" | "partially_answered"

The answered status.

metadataarray

A list of metadata filters.

tagsarray

A list of tags (case sensitive).

csat1 | 2 | 3 | 4 | 5

Thread CSAT score.

sentimentsarray

A list of sentiments (between -2 and 2).

urgenciesarray

A list of urgency scores (from 1 to 4).

escalatedboolean

Whether the thread is escalated or not.

expandstring

If set to data.messages, expand the thread object to include associated messages.

Example request

1curl "https://api.markprompt.com/threads?from=2024-04-01T22%3A00%3A00&to=2024-04-15T22%3A00%3A00&limit=3&page=1" \
2  -X GET \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-type: application/json" \
5  -H "Accept: application/json" \
6  -H "X-Markprompt-API-Version: 2024-03-23"

Response

The response is of the form:

1{
2  "object": "list",
3  "data": [
4    {
5      "id": "id-1",
6      "createdAt": "2023-08-07T22:36:37.728248+00:00",
7      "lastMessageCreatedAt": "2023-08-07T22:38:12.423211+00:00",
8      "answeredStatus": "answered",
9      "firstUserMessage": "How do I process a refund?",
10      "messageCount": 2,
11      "tags": ["Billing", "Platform"],
12      "votes": [1],
13      "sentiments": [0],
14      "urgencies": [0],
15      "metadata": {
16        "sessionId": "sessions-id-1"
17      }
18    }
19    // ...
20  ]
21}

It contains aggregated information about the messages in each thread, such as the average CSAT score and the highest urgency score, as well as a general assessment of whether the conversation can be considered as answered (or unanswered, or partially answered).

Expanded threads

When adding expand=data.messages to the request body, threads are returned together with associated messages.

1curl "https://api.markprompt.com/threads?from=2024-04-01T22%3A00%3A00&to=2024-04-02T22%3A00%3A00&limit=3&page=1&expand=data.messages" \
2  -X GET \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-type: application/json" \
5  -H "Accept: application/json" \
6  -H "X-Markprompt-API-Version: 2024-03-23"

The response looks like this:

1{
2  "object": "list",
3  "data": [
4    {
5      "id": "id-1",
6      // ...
7      "messages": [
8        {
9          "id": "message-id-1",
10          "createdAt": "2024-04-01T22:36:37.728248+00:00",
11          "role": "user",
12          "content": "How do I process a refund?",
13          "tags": ["Billing"],
14          "sentiment": 0,
15          "urgency": 0
16        },
17        {
18          "id": "message-id-2",
19          "role": "assistant",
20          "createdAt": "2024-04-01T22:36:41.34872+00:00",
21          "config": {
22            "systemPrompt": "You are a helpful AI assistant!",
23            "payloadConfig": {
24              // ...
25            }
26          },
27          "content": "You can create a refund...",
28          "vote": 1,
29          "answered": true,
30          "sentiment": 0,
31          "references": [
32            // ...
33          ]
34        }
35      ]
36    }
37    // ...
38  ]
39}

Filters

Here is an example that filters on metadata and tags:

1curl -X GET -G https://api.markprompt.com/threads \
2  -H "Authorization: Bearer <TOKEN>" \
3  -H "Content-type: application/json" \
4  -H "Accept: application/json" \
5  -H "X-Markprompt-API-Version: 2024-03-23" \
6  -d "limit=10" \
7  -d "from=2024-03-25T00:00:00Z" \
8  -d "to=2024-04-25T23:59:59" \
9  --data-urlencode "tags=[\"Billing\"]" \
10  --data-urlencode "metadata=[{ \"op\": \"eq\", \"field\": \"plan\", \"value\": \"starter\" }]" | jq

Supported metadata filter operators are: eq, neq, gt, lt, gte, lte, like, ilike, in, is, contains, containedBy, overlaps.

Thread messages

1GET https://api.markprompt.com/threads/{thread_id}/messages

Retrieves messages within a thread.

Example request

1curl "https://api.markprompt.com/threads/thread_123/messages" \
2  -X GET \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-type: application/json" \
5  -H "Accept: application/json" \
6  -H "X-Markprompt-API-Version: 2024-03-23"

Response

The response is of the form:

1{
2  "object": "list",
3  "data": [
4    {
5      "id": "message-id-1",
6      "createdAt": "2024-04-01T22:36:37.728248+00:00",
7      "role": "user",
8      "role": "what is markprompt in three words?",
9      "urgency": 1,
10      "sentiment": 0
11    },
12    {
13      "id": "message-id-2",
14      "createdAt": "2024-04-01T22:36:41.728248+00:00",
15      "response": "AI, support, API",
16      "csat": "4",
17      "systemPrompt": "You are kind AI who loves to help people!",
18      "config": {
19        // ...
20      },
21      "references": [
22        // ...
23      ]
24    }
25  ]
26}

Update a thread

1POST https://api.markprompt.com/threads/{thread_id}

Updates a thread.

Request body

KeyTypeDescription
csat1 | 2 | 3 | 4 | 5 | 0

A CSAT score. Set to 0 to clear value.

metadataobject

A metadata object.

strategymerge | overwrite

The update strategy. If set to merge, it will merge with the existing fields. If set to overwrite, it will replace the existing fields. Default: overwrite.

Example request

1curl "https://api.markprompt.com/threads/thread_123" \
2  -X POST \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-type: application/json" \
5  -H "X-Markprompt-API-Version: 2024-03-23" \
6  -d '{
7      "metadata": { "category": "payments" },
8      "csat": 3,
9      "strategy": "merge"
10    }'