POST
/api/glimpse/register
Creates a new companion account and returns an access token along with a unique couple invite code.
Request Body
{
"name": "Jane Doe",
"email": "jane@example.com",
"password": "secure_password"
}
JSON Response (200 OK)
{
"token": "1|sanctum_access_token",
"user": {
"id": 2,
"name": "Jane Doe",
"email": "jane@example.com",
"invite_code": "4D8F3E9C"
}
}
POST
/api/glimpse/login
Authenticate your existing developer/companion account to retrieve your persistent token.
Request Body
{
"email": "alex@example.com",
"password": "secure_password"
}
JSON Response (200 OK)
{
"token": "2|sanctum_access_token",
"user": {
"id": 1,
"name": "Alex",
"email": "alex@example.com",
"couple_id": 5
}
}
GET
/api/glimpse/state
Retrieves the complete real-time dashboard state, including your profile information, partner details, active couple connection info, and anniversary details.
JSON Response (200 OK)
{
"user": {
"id": 1,
"name": "Alex",
"battery_level": 94,
"is_charging": true,
"location_name": "Grand Indonesia",
"last_seen_message_id": 124
},
"partner_data": {
"id": 2,
"name": "Jane",
"battery_level": 72,
"is_charging": false,
"location_name": "Monas, Jakarta",
"last_seen_message_id": 123
},
"couple_active": true,
"anniversary_start_date": "2024-05-17 14:00:00"
}
POST
/api/glimpse/couple/link
Binds two users into a permanent connected couple by linking partner's unique 8-character invite code.
Request Body
{
"invite_code": "4D8F3E9C"
}
JSON Response (200 OK)
{
"message": "Couple link successfully established!",
"couple_id": 5
}
POST
/api/glimpse/location
Pushes your current GPS coordinates, speed, and geocoded landmark name. Connected partner devices will immediately update.
Request Body
{
"latitude": -6.200000,
"longitude": 106.816666,
"location_name": "Grand Indonesia Mall, Jakarta"
}
JSON Response (200 OK)
{
"success": true,
"message": "Location coordinates updated and broadcasted!"
}
POST
/api/glimpse/battery
Push real-time battery status changes (percentage and charging power adapter status) to trigger indicators.
Request Body
{
"battery_level": 84,
"is_charging": true
}
JSON Response (200 OK)
{
"success": true,
"message": "Battery pulse metrics synchronized!"
}
POST
/api/glimpse/chat
Sends an intimate chat message using custom Protobuf binary encoding. The iOS client encodes messages as binary fields (not JSON) for minimal payload size. Server decodes, persists, and broadcasts via WebSocket.
Request — Protobuf Binary (Content-Type: application/octet-stream)
Field 1 (varint): sender_id = 1
Field 2 (varint): room_id = 5
Field 3 (string): message = "Hey love!"
Field 4 (string): created_at= "2026-05-19T..."
// Encoded as raw binary, not JSON
// iOS: ChatMessage.encodeProtobuf()
Response — Protobuf Binary (200 OK)
Field 1 (varint): id = 125
Field 2 (varint): room_id = 5
Field 3 (varint): sender_id = 1
Field 4 (string): message = "Hey love!"
Field 5 (string): created_at= "2026-05-19T..."
// iOS: ChatMessage.decodeProtobuf(from: data)
POST
/api/glimpse/chat/read
Notifies the partner device that you have read up to a specific message ID, updating the 'Seen' checkmark status instantly.
Request Body
{
"message_id": 125
}
JSON Response (200 OK)
{
"success": true,
"last_seen_message_id": 125
}
POST
/api/glimpse/flashes
Uploads an intimate, secure flash photograph as a multi-part form-data capture to share on the active timeline feed.
Request Headers
Content-Type: multipart/form-data
Authorization: Bearer 2|sanctum_access_token
PROTO3
Protocol Buffer Specifications
To maximize performance and battery longevity, Glimpse bypasses heavy JSON strings for real-time location pushes and chat pipelines. The data is encoded into lightweight, binary Protocol Buffer payloads.
1. Chat Message Proto Schema
syntax = "proto3";
message ChatMessage {
int32 id = 1;
int32 room_id = 2;
int32 sender_id = 3;
string message = 4;
string created_at = 5;
}
This binary structure compresses a standard 300-byte JSON message down to just ~40-60 bytes.
2. User GPS & Battery Status Schema
syntax = "proto3";
message GlimpseUserStatus {
string latitude = 1; // String to prevent precision loss
string longitude = 2; // String to prevent precision loss
int32 battery_level = 3;
int32 is_charging = 4; // 0 = false, 1 = true
string status_note = 5;
string location_name = 6;
string wifi_bssid = 7;
}
3. Partner Live State Update Schema
syntax = "proto3";
message GlimpsePartnerStateUpdate {
int32 user_id = 1;
string latitude = 2;
string longitude = 3;
int32 battery_level = 4;
int32 is_charging = 5; // 0 = false, 1 = true
string status_note = 6;
string location_name = 7;
string wifi_bssid = 8;
int32 last_seen_message_id = 9;
}
Swift Client Implementation Code
The iOS application encodes variables manually using a high-speed bitwise `ProtobufWriter` and parses incoming streams using `ProtobufReader`, minimizing external library dependencies:
// Manual Protobuf Serialization in Swift (GlimpseProtobuf.swift)
struct ProtobufWriter {
private(set) var data = Data()
mutating func writeVarint(_ val: UInt64) {
var value = val
while value >= 0x80 {
data.append(UInt8((value & 0x7F) | 0x80))
value >>= 7
}
data.append(UInt8(value & 0x7F))
}
mutating func writeTag(fieldNumber: Int, wireType: Int) {
writeVarint(UInt64((fieldNumber << 3) | wireType))
}
mutating func writeInt32Field(fieldNumber: Int, value: Int) {
writeTag(fieldNumber: fieldNumber, wireType: 0)
writeVarint(UInt64(value))
}
mutating func writeStringField(fieldNumber: Int, value: String) {
guard let stringData = value.data(using: .utf8) else { return }
writeTag(fieldNumber: fieldNumber, wireType: 2)
writeVarint(UInt64(stringData.count))
data.append(stringData)
}
}
Laravel PHP Parser & Server Broadcast
When the Laravel backend receives the raw binary request header `Content-Type: application/x-protobuf`, it handles it using a PHP Protobuf decoder to decode message tags:
// Laravel Controller: Decoding Protobuf Bytes & Broadcasting
public function sendProtobufChat(Request $request) {
$rawBytes = $request->getContent();
// Decodes Proto3 Fields (1=id, 2=roomId, 3=senderId, 4=message, 5=createdAt)
$protoMessage = new \App\Protobuf\ChatMessage();
$protoMessage->mergeFromString($rawBytes);
// Store in MySQL database persistent schema
$chat = ChatMessage::create([
'room_id' => $protoMessage->getRoomId(),
'sender_id' => $protoMessage->getSenderId(),
'message' => $protoMessage->getMessage(),
]);
// Prepare Base64 encoded payload for real-time WebSocket distribution
$encodedBase64 = base64_encode($rawBytes);
// Broadcast via Pusher WebSockets to listening partner devices
broadcast(new GlimpseChatEvent($chat->couple_id, $encodedBase64))->toOthers();
return response($rawBytes)->header('Content-Type', 'application/x-protobuf');
}