API Reference
Complete REST API reference for QrioTag — base URL, authentication, environments, response format, pagination, and error handling.
Environments
Use the switcher below to select your target environment. Copy the base URL and use it in your requests.
Live environment — real data
https://api.qriotag.global/api/v1All Environments
https://api.qriotag.global/api/v1https://staging-api.qriotag.global/api/v1http://localhost:4000/api/v1Staging environment
The staging environment uses test data and mirrors production closely. Use it for integration testing before going live. Never use real payment credentials on staging.
API Categories
Authentication
Register, login, 2FA, API keys, and session management — everything for identity and access.
Tags
Activate, update status, transfer, view scan history, and manage insurance per tag.
Profiles
General, pet, vehicle, device, and travel profile data — including photo uploads.
Scans
Public scan page, anonymous contact form, and finder conversation thread endpoints.
Messages
Owner-to-finder messaging — threads, replies, and read status tracking.
Rewards
Create, confirm return, process payout, dispute, and issue proof-of-return certificates.
Vehicles
Report stolen vehicles, VIN verification, and vehicle-specific tag features.
Notifications
List, mark read, push token registration, SSE stream, and notification preferences.
Orders
Create orders, Stripe checkout, invoice download, and subscription management.
Emergency
Medical profile and emergency contacts — data designed for first responders.
Blog
List and retrieve published posts. Admin endpoints for create, update, and delete.
Contact
Contact form submission and newsletter subscriber management.
Reports
Submit user reports, list reports (admin), and block abusive users.
Admin
Platform stats, user management, analytics, campaigns, and configuration.
Webhooks
Stripe event handler — payment confirmations, subscription changes, and refunds.
Authentication
Three methods are supported:
| Method | Header | Use case |
|---|---|---|
| Bearer token | Authorization: Bearer <accessToken> | Frontend apps, scripts |
| httpOnly cookie | Set automatically on login | Browser-based apps |
| API key | X-API-Key: <key> | Server-to-server integrations |
Token lifetime: Access token = 15 min · Refresh token = 7 days
# Bearer token
curl https://api.qriotag.global/api/v1/auth/me \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
# API key
curl https://api.qriotag.global/api/v1/tags \
-H "X-API-Key: qtk_live_abc123..."# Bearer token
curl https://staging-api.qriotag.global/api/v1/auth/me \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
# API key
curl https://staging-api.qriotag.global/api/v1/tags \
-H "X-API-Key: qtk_test_abc123..."# Bearer token
curl http://localhost:4000/api/v1/auth/me \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
# API key
curl http://localhost:4000/api/v1/tags \
-H "X-API-Key: qtk_dev_abc123..."Response Format
Every response follows a consistent JSON structure.
Success
{
"success": true,
"data": {
"id": "usr_abc123",
"email": "user@example.com",
"firstName": "Jane"
}
}Success with pagination
{
"success": true,
"data": [
{ "id": "tag_001", "itemName": "House Keys" },
{ "id": "tag_002", "itemName": "Backpack" }
],
"meta": {
"total": 42,
"page": 1,
"totalPages": 5
}
}Error
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email address",
"details": [
{ "field": "email", "message": "Must be a valid email" }
]
}
}Pagination
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
page | integer | 1 | — | Page number (1-based) |
limit | integer | 10 | 100 | Items per page |
curl "https://api.qriotag.global/api/v1/tags?page=2&limit=20" \
-H "Authorization: Bearer <token>"curl "https://staging-api.qriotag.global/api/v1/tags?page=2&limit=20" \
-H "Authorization: Bearer <token>"curl "http://localhost:4000/api/v1/tags?page=2&limit=20" \
-H "Authorization: Bearer <token>"Rate Limiting
| Scope | Limit | Endpoints |
|---|---|---|
| General | 100 req/min | Most authenticated endpoints |
| Auth | 10 req/min | Login, register, password reset |
| Public scan | 30 req/min | GET /scan/:id |
| Emergency scan | 5 req/min | GET /scan/:id/emergency |
| Registration | 5 req/hr | POST /auth/register |
| Password reset | 3 req/hr | POST /auth/forgot-password |
| Contact form | 3 req/hr | POST /contact |
Rate limit headers in every response:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1700000000When exceeded — HTTP 429:
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again later."
}
}Error Codes
| Status | Code | Meaning |
|---|---|---|
400 | VALIDATION_ERROR | Request body or params failed validation |
401 | UNAUTHORIZED | Missing or invalid authentication |
403 | FORBIDDEN | Authenticated but insufficient permissions |
404 | NOT_FOUND | Resource does not exist |
409 | CONFLICT | Resource already exists or state conflict |
422 | UNPROCESSABLE_ENTITY | Request understood but cannot be processed |
429 | RATE_LIMIT_EXCEEDED | Too many requests |
500 | INTERNAL_ERROR | Server error — contact support |
HTTP Methods
| Method | Usage |
|---|---|
GET | Read resources — never modifies data |
POST | Create resources or trigger actions |
PATCH | Partially update a resource |
PUT | Replace a resource or sub-resource entirely |
DELETE | Remove a resource |
Interactive Explorer
Swagger UI is available on all environments:
| Environment | URL |
|---|---|
| Production | https://api.qriotag.global/docs |
| Staging | https://staging-api.qriotag.global/docs |
| Development | http://localhost:4000/docs |
Test endpoints directly from the browser, inspect schemas, and view all available routes.
Quick Start
Start with Authentication — register an account and get tokens, then explore any category from the sidebar.
Was this page helpful?