Guaranteed network quality

Request a guaranteed network profile — higher bandwidth, lower latency — for a specific device, for a defined window. Use it for the moments that need it: a video consultation, a live broadcast, a cloud-gaming session, a drone control link. This guide covers the session lifecycle and how to handle its asynchronous callbacks.

How QoD differs from the other APIs

Number Verification, SIM Swap, and KYC are single request/response checks. Quality on Demand is a session: you create it, it stays active for a duration, then it expires (or you delete it). Because the network provisions the profile asynchronously, status changes arrive via callbacks — you give Konera a URL, and it notifies you when the session activates, expires, or fails.

What you'll need

• An application registered to Quality on Demand (see Your first verified API call)
• A valid access token with the QoD scope (see OAuth2 with Konera)
• A publicly reachable HTTPS callback URL (see Working with callbacks)
• The device's phone number, and the QoS profile you want (e.g. QOS_L for low latency)

Step 1 — Create a session

Request the profile for the device, set a duration (seconds), and supply your callback URL.

curl -X POST https://api.pxg.konera.com/camara/qod/v0/sessions \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"device": { "phoneNumber": "+14155550123" },
"qosProfile": "QOS_L",
"duration": 3600,
"webhook": { "notificationUrl": "https://app.example.com/qod/callbacks" }
}'

Response — the session is created and starts provisioning:

{
"sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"qosProfile": "QOS_L",
"qosStatus": "REQUESTED",
"startedAt": "2026-06-02T09:00:00Z",
"expiresAt": "2026-06-02T10:00:00Z"
}

Step 2 — Receive the activation callback

When the network finishes provisioning, Konera POSTs to your notificationUrl. Don't poll — react to the callback.

POST /qod/callbacks
{
"sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"event": "QOS_STATUS_CHANGED",
"qosStatus": "AVAILABLE"
}

On AVAILABLE, the guaranteed profile is active — start the session that needs it. If you instead receive UNAVAILABLE, the network couldn't honour the profile — fall back to best-effort and inform the user.

Step 3 — Check or end the session

Read a session's current state at any time:

curl https://api.pxg.konera.com/camara/qod/v0/sessions/$SESSION_ID \
-H "Authorization: Bearer $TOKEN"

Sessions expire automatically at duration. Release early when the activity ends — you stop paying for capacity you no longer need:

curl -X DELETE https://api.pxg.konera.com/camara/qod/v0/sessions/$SESSION_ID \
-H "Authorization: Bearer $TOKEN"

Choosing a QoS profile

Getting it right

• Always handle UNAVAILABLE. A guaranteed profile can be refused under congestion — design a best-effort fallback, never a hard failure.
• Acknowledge callbacks fast (2xx within a few seconds) and process asynchronously, or Konera will retry (see Working with callbacks).
• Verify callback authenticity before acting — validate the signature so a spoofed POST can't trigger your flow.
• Release early. Delete the session the moment the user's activity ends; don't wait for expiry.
• Match duration to the activity. Over-long sessions waste guaranteed capacity; too-short ones expire mid-use.

Next steps

• Working with callbacks — verifying, acknowledging, and retrying notifications.
• Testing with sandbox numbers — drive each session state and callback in the sandbox.
• Rate limits & error handling — error shapes and retry behaviour.