Choosing your API version
Livstick exposes two client APIs side by side: v3 and 2.1. This page answers one question — which one to start with, and why — so the rest of Build can assume you have already made that call.
Start on v3
If you are starting a new integration, build it on v3. It is the current API and the one this documentation leads with. It exposes a paginated list of containers and messages, direct access to messages, code groups in read, unlock kept separate from notify, gallery mode, and typed sender and recipient contacts with an explicit channel choice — none of which exist in 2.1.
- API v3 reference
- The full v3 reference — containers, messages, code groups, and errors.
When 2.1 still matters
2.1 remains the right choice in two specific cases, and only those two.
- Your integration calls retarget — reassigning a container’s contact, language, code group, or additional data after creation.
- Your integration relies on webhook delivery (messageUnlockEvent) to be notified when a message is unlocked.
- 2.1: retarget
- Reassigning a container’s contact, language, code group, or additional data after creation.
- 2.1: webhooks
- messageUnlockEvent delivery, for being notified when a message is unlocked.
- API 2.1 reference
- The full 2.1 reference, for the rest of what stays on that API.
- Migrating from 2.1 to v3
- For an integration already on 2.1, what maps to v3 and what does not.
v3 compared with 2.1
The two APIs are not layered — each has capabilities the other does not.
| Capability | v3 | 2.1 |
|---|---|---|
| Paginated list of containers and messages | Yes | No |
| Direct access to messages (read and write) | Yes | No |
| Code groups in read | Yes | No |
| unlock kept separate from notify | Yes | No |
| Gallery mode (multiple messages per container) | Yes | No |
| Typed sender / recipient contacts with channel choice | Yes | No |
| retarget | No | Yes |
| Webhooks (messageUnlockEvent) | No | Yes |
One key system, either version
Choosing a version is not an infrastructure decision. v3 and 2.1 authenticate against the same key management system — keys issued from that system are what call both APIs, not two separate setups to provision and rotate.