Messages API
Manage finder-to-owner message threads, view conversations, send replies, and mark messages as read.
The Messages API lets tag owners manage their conversations with finders. Finders use the Scans API thread endpoints instead. All endpoints require authentication.
List Threads
GET /api/v1/messages — Required
Get Thread
GET /api/v1/messages/:threadId — Required
Reply
POST /api/v1/messages/:threadId/reply — Required
Mark as Read
PATCH /api/v1/messages/:threadId/read — Required
List Message Threads
Retrieve all message threads for the authenticated user.
GET /api/v1/messages — Auth: Required
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
limit | integer | 10 | Items per page |
curl "https://api.qriotag.global/api/v1/messages?page=1&limit=10" \
-H "Authorization: Bearer <token>"Response
{
"success": true,
"data": [
{
"id": "thr_abc123",
"tagId": "tag_abc123",
"tagName": "House Keys",
"finderName": "Alex",
"lastMessage": "Yes, 5pm works!",
"unreadCount": 1,
"status": "ACTIVE",
"createdAt": "2025-06-01T15:35:00.000Z",
"updatedAt": "2025-06-01T16:00:00.000Z"
}
],
"meta": {
"total": 3,
"page": 1,
"totalPages": 1
}
}Get Thread Messages
Retrieve all messages in a specific thread.
GET /api/v1/messages/:threadId — Auth: Required
curl https://api.qriotag.global/api/v1/messages/thr_abc123 \
-H "Authorization: Bearer <token>"Response
{
"success": true,
"data": {
"threadId": "thr_abc123",
"tagId": "tag_abc123",
"tagName": "House Keys",
"finderName": "Alex",
"status": "ACTIVE",
"messages": [
{
"id": "msg_001",
"sender": "FINDER",
"content": "I found your keys at the coffee shop on Main Street.",
"createdAt": "2025-06-01T15:35:00.000Z"
},
{
"id": "msg_002",
"sender": "OWNER",
"content": "Thank you! Can we meet there at 5pm?",
"createdAt": "2025-06-01T15:50:00.000Z"
}
]
}
}Reply to Thread
Send a reply as the tag owner.
POST /api/v1/messages/:threadId/reply — Auth: Required
Request body
| Field | Type | Required | Description |
|---|---|---|---|
content | string | Yes | Reply message content |
curl -X POST https://api.qriotag.global/api/v1/messages/thr_abc123/reply \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "content": "Great, see you at 5pm! I will be at the counter." }'Response
{
"success": true,
"data": {
"id": "msg_003",
"sender": "OWNER",
"content": "Great, see you at 5pm! I will be at the counter.",
"createdAt": "2025-06-01T16:05:00.000Z"
}
}Mark Thread as Read
Mark all messages in a thread as read.
PATCH /api/v1/messages/:threadId/read — Auth: Required
curl -X PATCH https://api.qriotag.global/api/v1/messages/thr_abc123/read \
-H "Authorization: Bearer <token>"Response
{
"success": true,
"data": {
"message": "Thread marked as read"
}
}Was this page helpful?