Skip to main content
API docs by Redocly

Splick Backend API (0.0.5)

Download OpenAPI specification:Download

Splick modular monolith — public API via Kong Gateway OSS (/api prefix).

Source of truth for Postman Spec Hub sync. After editing this file, run: make postman-sync or ask the agent to sync the collection.

Admin

Operator console (username/password). Not for mobile clients.

Admin login

Request Body schema: application/json
required
username
required
string
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0
}

Rotate admin refresh token

Request Body schema: application/json
required
refreshToken
required
string

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0
}

Revoke admin refresh token

Authorizations:
bearerAuth
Request Body schema: application/json
required
refreshToken
required
string

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Search app users

Authorizations:
bearerAuth
query Parameters
query
string
status
string
Enum: "ACTIVE" "INACTIVE" "LOCKED"
from
string <date-time>
to
string <date-time>
page
integer >= 0
Default: 0
limit
integer [ 1 .. 200 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "limit": 0,
  • "total": 0,
  • "hasMore": true
}

Lock an app user

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "username": "string",
  • "displayName": "string",
  • "phoneNumber": "string",
  • "status": "string",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Unlock an app user

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "username": "string",
  • "displayName": "string",
  • "phoneNumber": "string",
  • "status": "string",
  • "createdAt": "2019-08-24T14:15:22Z"
}

List trial registrations

Authorizations:
bearerAuth
query Parameters
status
string
Enum: "PENDING" "WHITELISTED" "APPROVED" "REJECTED"

Omit or leave blank to return every status.

platform
string
Enum: "ios" "android"

Omit or leave blank to return every platform.

email
string

Case-insensitive substring match on the registrant email.

from
string <date>

Inclusive start of createdAt, as a calendar date in Asia/Ho_Chi_Minh.

to
string <date>

Inclusive end of createdAt, as a calendar date in Asia/Ho_Chi_Minh.

page
integer
Default: 0
limit
integer
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "limit": 0,
  • "total": 0,
  • "hasMore": true
}

Export trial CSV and mark Android PENDING as WHITELISTED

Exports Android emails for Google Play Console tester import (one email per line, no header). Android PENDING rows in the export set are marked WHITELISTED in the same transaction. iOS rows are omitted. Cap 5000 rows.

Authorizations:
bearerAuth
query Parameters
status
string
Enum: "PENDING" "WHITELISTED" "APPROVED" "REJECTED"
platform
string
Enum: "ios" "android"
email
string
from
string <date>
to
string <date>

Responses

Response samples

Content type
application/json
{ }

Approve a trial registration

iOS may be approved from PENDING; Android requires WHITELISTED first. Idempotent when already APPROVED.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "platform": "ios",
  • "status": "PENDING",
  • "locale": "en",
  • "approvedAt": "2019-08-24T14:15:22Z",
  • "rejectedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Reject a PENDING or WHITELISTED trial

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "platform": "ios",
  • "status": "PENDING",
  • "locale": "en",
  • "approvedAt": "2019-08-24T14:15:22Z",
  • "rejectedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List post reports

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0
limit
integer
Default: 20
reason
string
Enum: "SPAM" "HARASSMENT" "HATE_SPEECH" "NUDITY" "VIOLENCE" "MISINFORMATION" "SCAM" "OTHER"

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "limit": 0,
  • "total": 0,
  • "hasMore": true
}

List Android and iOS release rows

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a store release version and download link

Authorizations:
bearerAuth
path Parameters
platform
required
string
Enum: "android" "ios" "ios-testflight"
Request Body schema: application/json
required
latestVersionCode
required
integer <int32> >= 0
latestVersionName
required
string <= 32 characters
storeUrl
required
string <= 512 characters
forceUpdate
required
boolean

Responses

Request samples

Content type
application/json
{
  • "latestVersionCode": 0,
  • "latestVersionName": "string",
  • "storeUrl": "string",
  • "forceUpdate": true
}

Response samples

Content type
application/json
{
  • "platform": "string",
  • "latestVersionCode": 0,
  • "latestVersionName": "string",
  • "storeUrl": "string",
  • "forceUpdate": true,
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get full post details for admin moderation

Authorizations:
bearerAuth
path Parameters
postId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "author": {
    },
  • "mediaItems": [
    ],
  • "caption": "string",
  • "mentions": [
    ],
  • "reactions": [
    ],
  • "reactionCount": 0,
  • "reactorCount": 0,
  • "reactionPreview": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "groupIds": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "editedAt": "2019-08-24T14:15:22Z",
  • "companions": [
    ],
  • "feedKind": "string",
  • "checkInPlace": "string",
  • "location": {
    },
  • "audience": {
    },
  • "billSplit": {
    },
  • "comments": [
    ],
  • "commentCount": 0,
  • "viewCount": 0,
  • "viewers": [
    ]
}

Hide a reported post from the feed

Authorizations:
bearerAuth
path Parameters
postId
required
string <uuid>

Responses

Auth

Registration, login, tokens, profile

Check whether email or phone is already registered

Provide exactly one of email or phoneNumber. Used by the unified login screen to decide between sign-in and sign-up fields.

Request Body schema: application/json
required
email
string <email>
phoneNumber
string^\+?[1-9]\d{7,14}$

Responses

Request samples

Content type
application/json
Example
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "exists": true
}

Check username availability

Returns whether the username is available for registration or profile update. When called with a valid Bearer token, the current user's own username is treated as available.

Request Body schema: application/json
required
username
required
string [ 3 .. 50 ] characters ^[a-zA-Z0-9_.]+$

Letters, numbers, underscores, and dots only

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "available": true
}

Register user

Register with email or phone (exactly one).

  1. Request OTP: POST /v1/auth/email/otp/request or POST /v1/auth/phone/otp/request
  2. Submit register with otpCode (6 digits)

Account linking: If the email already belongs to a Google-only account (signed in with Google first, no password yet), a verified email OTP completes the account by attaching a password. Existing username and Google link are preserved; displayName is updated only when the account has none. Returns the same AuthResponse as a new registration (201). If the email already has a password, returns 409 with error: EMAIL_ALREADY_REGISTERED. If the phone already has a password, returns 409 with error: PHONE_ALREADY_REGISTERED. Phone OTP login first, then phone register: attaches a password (same as Google → email register).

Request Body schema: application/json
required
email
string <email>
phoneNumber
string^\+?[1-9]\d{7,14}$
otpCode
required
string^\d{6}$
username
required
string [ 3 .. 50 ] characters ^[a-zA-Z0-9_.]+$

Letters, numbers, underscores, and dots

password
required
string [ 8 .. 100 ] characters ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*...

At least 8 characters with uppercase, lowercase, digit, and special character (!@#$%^&* etc.)

displayName
string <= 150 characters

Optional. When omitted or blank, the username is used.

dateOfBirth
string or null <date>

Optional. Must be in the past and at least 13 years old when provided.

deviceInfo
string
deviceName
string

Human-readable device label (e.g. iPhone 15)

loginLocation
string

Client-reported approximate location (e.g. region, timezone)

Responses

Request samples

Content type
application/json
Example
{
  • "email": "user@example.com",
  • "otpCode": "123456",
  • "username": "johndoe",
  • "password": "secureP@ss123",
  • "displayName": "John Doe"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false
}

Register for product trial

Public marketing endpoint to capture interest in trying Splick. Requires email and preferred mobile platform (ios or android). Optional locale (en|vi) selects email language (default en). On success, a confirmation email is enqueued asynchronously. Each email may register only once; a duplicate returns 409 with error: TRIAL_EMAIL_ALREADY_REGISTERED.

Request Body schema: application/json
required
email
required
string <email> <= 255 characters
platform
required
string
Enum: "ios" "android"

Preferred mobile platform for the trial.

locale
string
Enum: "en" "vi"

Preferred email locale. Defaults to en when omitted.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "platform": "ios",
  • "locale": "en"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "platform": "ios",
  • "status": "PENDING",
  • "locale": "en",
  • "approvedAt": "2019-08-24T14:15:22Z",
  • "rejectedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Sign in with Google ID token (mobile / native)

Exchange a Google ID token from Google Sign-In (iOS/Android) for Splick JWTs. Configure GOOGLE_IOS_CLIENT_ID on auth-service to match the iOS OAuth client aud claim. New accounts set newUser to true and default user.displayName to the email local-part (text before @).

Request Body schema: application/json
required
idToken
required
string

Google ID token from Sign-In SDK

deviceInfo
string
deviceName
string
loginLocation
string

Responses

Request samples

Content type
application/json
{
  • "idToken": "string",
  • "deviceInfo": "string",
  • "deviceName": "string",
  • "loginLocation": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false
}

Sign in with Apple ID token (mobile / native)

Exchange an Apple identity token from Sign in with Apple (iOS) for Splick JWTs. Configure AUTH_APPLE_IOS_BUNDLE_ID on auth-service to match the iOS app bundle ID (aud claim). New accounts set newUser to true and default user.displayName to the email local-part (text before @).

Request Body schema: application/json
required
idToken
required
string

Apple identity token from Sign in with Apple

deviceInfo
string
deviceName
string
loginLocation
string

Responses

Request samples

Content type
application/json
{
  • "idToken": "string",
  • "deviceInfo": "string",
  • "deviceName": "string",
  • "loginLocation": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false
}

Login with email and password

Request Body schema: application/json
required
email
required
string <email>
password
required
string
deviceInfo
string
deviceName
string
loginLocation
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "string",
  • "deviceInfo": "string",
  • "deviceName": "string",
  • "loginLocation": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false
}

Enable quick login for the current device

Authorizations:
bearerAuth
Request Body schema: application/json
required
deviceId
required
string
deviceInfo
string
deviceName
string

Responses

Request samples

Content type
application/json
{
  • "deviceId": "string",
  • "deviceInfo": "string",
  • "deviceName": "string"
}

Response samples

Content type
application/json
{
  • "quickLoginToken": "string",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Authenticate using a device-bound quick login token

Request Body schema: application/json
required
quickLoginToken
required
string
deviceId
required
string
deviceInfo
string
deviceName
string
loginLocation
string

Responses

Request samples

Content type
application/json
{
  • "quickLoginToken": "string",
  • "deviceId": "string",
  • "deviceInfo": "string",
  • "deviceName": "string",
  • "loginLocation": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false,
  • "quickLoginToken": "string",
  • "quickLoginExpiresAt": "2019-08-24T14:15:22Z"
}

Revoke a device-bound quick login token

Request Body schema: application/json
required
quickLoginToken
required
string
deviceId
required
string

Responses

Request samples

Content type
application/json
{
  • "quickLoginToken": "string",
  • "deviceId": "string"
}

Request password reset OTP by email

Always returns 202 Accepted (does not reveal whether the email exists), including when OTP send is throttled for that destination. OTP is sent only for accounts with a normal email address (not phone-only @phone.splick.local). Gateway may return 429 for per-IP abuse limits.

Request Body schema: application/json
required
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{ }

Verify password-reset OTP (without consuming)

Validates the email OTP from POST /v1/auth/password/forgot without consuming it. Use before the new-password step; then call POST /v1/auth/password/reset.

Request Body schema: application/json
required
email
required
string <email>
otpCode
required
string = 6 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "otpCode": "string"
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Reset password with email OTP

Verifies email OTP, sets a new password, revokes existing refresh tokens, and returns a new session. Works for email/password accounts and Google-only accounts (adds a password).

Request Body schema: application/json
required
email
required
string <email>
otpCode
required
string = 6 characters
newPassword
required
string
deviceInfo
string
deviceName
string
loginLocation
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "otpCode": "string",
  • "newPassword": "string",
  • "deviceInfo": "string",
  • "deviceName": "string",
  • "loginLocation": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false
}

Change password (authenticated)

Provide either currentPassword or otpCode (from POST /v1/auth/email/otp/request), plus newPassword. Revokes other refresh tokens and returns a new token pair.

Authorizations:
bearerAuth
Request Body schema: application/json
required
currentPassword
string
otpCode
string = 6 characters
newPassword
required
string
deviceInfo
string
deviceName
string
loginLocation
string

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string",
  • "otpCode": "string",
  • "newPassword": "string",
  • "deviceInfo": "string",
  • "deviceName": "string",
  • "loginLocation": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false
}

Verify password-change credentials (authenticated)

Validates either currentPassword or otpCode (from POST /v1/auth/email/otp/request) without changing the password. Email OTP is checked but not consumed — use before showing the new-password step, then call POST /v1/auth/password/change.

Authorizations:
bearerAuth
Request Body schema: application/json
required
currentPassword
string
otpCode
string = 6 characters

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string",
  • "otpCode": "string"
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Refresh access token

Request Body schema: application/json
required
refreshToken
required
string

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false
}

Logout current device session

Authorizations:
bearerAuth
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

List active refresh-token sessions

Authorizations:
bearerAuth
header Parameters
X-Refresh-Token
string

Optional refresh token to mark the current session

Responses

Response samples

Content type
application/json
[
  • { }
]

Revoke all refresh-token sessions

Authorizations:
bearerAuth

Responses

Revoke a single session

Authorizations:
bearerAuth
path Parameters
sessionId
required
string <uuid>

Responses

Deactivate account

Authorizations:
bearerAuth
Request Body schema: application/json
required
currentPassword
string
otpCode
string = 6 characters

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string",
  • "otpCode": "string"
}

Unpaid debts warning before account deletion

Returns whether the signed-in user still owes other people. The warning does not block deletion. On an upstream failure the flag is false.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "hasUnpaidDebtsToOthers": true
}

Request account deletion (public web)

Public Play Console / web deletion request. Does not delete or deactivate immediately. Always returns 202 with a generic message (anti-enumeration). When an ACTIVE account matches the email, sends a confirmation link valid for 48 hours. Web deletion is email only. Confirm via /v1/auth/account/deletion-requests/confirm, which deletes the account immediately.

Request Body schema: application/json
required
identifier
required
string <= 255 characters

Registered email address. Phone numbers are rejected.

reason
string <= 1000 characters

Optional reason for leaving.

Responses

Request samples

Content type
application/json
{
  • "identifier": "user@example.com",
  • "reason": "Switching apps"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Confirm account deletion request

Confirms the emailed link (valid 48 hours) and deletes the account immediately. There is no extra 30-day grace after this step.

Request Body schema: application/json
required
token
required
string <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "token": "url-safe-token-from-email"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "deletedAt": "2019-08-24T14:15:22Z"
}

Reactivate a deactivated account

Public endpoint. Use the reactivationToken returned with ACCOUNT_INACTIVE after a successful credential check. Restores the account during the 30-day grace period and issues a new session.

Request Body schema: application/json
required
reactivationToken
required
string
deviceInfo
string
deviceName
string
loginLocation
string

Responses

Request samples

Content type
application/json
{
  • "reactivationToken": "string",
  • "deviceInfo": "string",
  • "deviceName": "string",
  • "loginLocation": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false
}

Soft-delete account

Authorizations:
bearerAuth
Request Body schema: application/json
required
currentPassword
string
otpCode
string = 6 characters

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string",
  • "otpCode": "string"
}

List linked sign-in methods

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{ }

Link Google to current account

Authorizations:
bearerAuth
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Unlink Google from current account

Authorizations:
bearerAuth
Request Body schema: application/json
required
currentPassword
string
otpCode
string = 6 characters

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string",
  • "otpCode": "string"
}

Send OTP to link phone to current account

Authorizations:
bearerAuth
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Link phone number to current account

Authorizations:
bearerAuth
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Send OTP to link email to current account

Authorizations:
bearerAuth
Request Body schema: application/json
required
email
required
string <email>
purpose
string
Enum: "account_deactivate" "account_delete" "google_unlink"

Optional. account_deactivate, account_delete, or google_unlink selects that OTP email. Omit for registration (unknown email) or password change (existing account).

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "purpose": "account_deactivate"
}

Link email to current account (OTP verified; password optional)

Authorizations:
bearerAuth
Request Body schema: application/json
required
email
string <email>

Required for phone-only accounts; ignored when the account already has a recoverable email.

otpCode
required
string = 6 characters
password
string <= 100 characters

Optional. Omit to link email via OTP only; create a password later from account settings.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "otpCode": "string",
  • "password": "string"
}

Find an active user by exact email

Used when adding someone to a bill split from an email address. Returns the public profile (no email) when that address belongs to an active Splick account. Returns 404 when it does not, so the client can send a guest invite.

Authorizations:
bearerAuth
query Parameters
email
required
string <email> <= 254 characters

Responses

Response samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "username": "string",
  • "displayName": "string",
  • "avatarUrl": "string"
}

Get current user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "username": "string",
  • "displayName": "string",
  • "avatarUrl": "string",
  • "status": "ACTIVE",
  • "preferredLocale": "vi",
  • "timezone": "Asia/Ho_Chi_Minh",
  • "dateOfBirth": "2000-05-15",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "hasPassword": true
}

Update current user profile

Updates display name, username, avatar URL, preferred locale (vi|en), IANA timezone, and/or date of birth. At least one field required. Publishes UserProfileUpdatedEvent for social user_projection sync.

Authorizations:
bearerAuth
Request Body schema: application/json
required
displayName
string [ 1 .. 100 ] characters
username
string [ 3 .. 50 ] characters ^[a-zA-Z0-9_.]+$
avatarUrl
string <= 500 characters
preferredLocale
string
Enum: "vi" "en"
timezone
string <= 64 characters

IANA time zone (for example Asia/Ho_Chi_Minh). Used as the user's streak calendar.

dateOfBirth
string <date>

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "username": "string",
  • "avatarUrl": "string",
  • "preferredLocale": "vi",
  • "timezone": "America/Los_Angeles",
  • "dateOfBirth": "2000-05-15"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "username": "string",
  • "displayName": "string",
  • "avatarUrl": "string",
  • "status": "ACTIVE",
  • "preferredLocale": "vi",
  • "timezone": "Asia/Ho_Chi_Minh",
  • "dateOfBirth": "2000-05-15",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "hasPassword": true
}

Get my payment profile

Returns the authenticated user's payment QR image URL and/or bank account details.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "qrImageUrl": "string",
  • "accountName": "string",
  • "accountNumber": "string",
  • "bankName": "string",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Upsert my payment profile

Creates or replaces the authenticated user's payment profile. Validation requires either qrImageUrl or the full bank set (accountName, accountNumber, bankName).

Authorizations:
bearerAuth
Request Body schema: application/json
required
qrImageUrl
string <= 2048 characters

Public URL from completed USER_PAYMENT_QR media upload

accountName
string <= 200 characters
accountNumber
string <= 50 characters

Digits only

bankName
string <= 200 characters

Responses

Request samples

Content type
application/json
{
  • "qrImageUrl": "string",
  • "accountName": "string",
  • "accountNumber": "string",
  • "bankName": "string"
}

Response samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "qrImageUrl": "string",
  • "accountName": "string",
  • "accountNumber": "string",
  • "bankName": "string",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete my payment profile

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Validate access token

Service-to-service token validation.

Request Body schema: application/json
required
accessToken
required
string

Responses

Request samples

Content type
application/json
{
  • "accessToken": "string"
}

Response samples

Content type
application/json
{ }

Email OTP

Email verification codes for registration

Send email OTP

Sends a 6-digit email OTP. Per-destination send cooldown and max resends apply; exceeding them returns 429 with error: OTP_SEND_RATE_LIMIT.

Request Body schema: application/json
required
email
required
string <email>
purpose
string
Enum: "account_deactivate" "account_delete" "google_unlink"

Optional. account_deactivate, account_delete, or google_unlink selects that OTP email. Omit for registration (unknown email) or password change (existing account).

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "purpose": "account_deactivate"
}

Response samples

Content type
application/json
{ }

Phone OTP

SMS OTP for registration and phone login

Send phone OTP (SMS)

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Verify phone OTP and login

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false
}

OAuth2

Google OAuth2 (browser flow)

Start Google OAuth2 (browser)

Open in browser via gateway. After Google sign-in, Spring Security handles GET /v1/auth/oauth2/code/google and returns JSON tokens (see callback operation).

Responses

Google OAuth2 callback (handled by Spring Security)

Do not call manually. Browser redirect targets: https://api.splick.app/api/v1/auth/oauth2/code/google (prod), http://localhost:8080/api/v1/auth/oauth2/code/google (local).

Responses

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "expiresIn": 0,
  • "tokenType": "Bearer",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "user": {
    },
  • "newUser": false
}

Social

Social-service bootstrap and health

Bootstrap health check (JWT)

Verifies JWT auth wiring. Replace with real APIs as features land.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
}

Social Users

User search (user_projection)

Search users by username

Authorizations:
bearerAuth
query Parameters
q
required
string [ 1 .. 100 ] characters

Username search prefix

page
integer >= 0
Default: 0
size
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

Get nearby discovery preference

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "nearbyEnabled": true
}

Update nearby discovery preference

Authorizations:
bearerAuth
Request Body schema: application/json
required
nearbyEnabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "nearbyEnabled": true
}

Response samples

Content type
application/json
{
  • "nearbyEnabled": true
}

List recent search queries for a scope

Authorizations:
bearerAuth
query Parameters
scope
required
string (SearchHistoryScope)
Enum: "FRIENDS" "MESSAGING" "MESSAGING_THREAD" "ALBUM" "LOCATION" "EXPENSE" "GIF"
scopeKey
string <= 64 characters

Conversation id when scope is MESSAGING_THREAD

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Record a search query

Authorizations:
bearerAuth
Request Body schema: application/json
required
scope
required
string (SearchHistoryScope)
Enum: "FRIENDS" "MESSAGING" "MESSAGING_THREAD" "ALBUM" "LOCATION" "EXPENSE" "GIF"
query
required
string [ 1 .. 100 ] characters
scopeKey
string or null <= 64 characters

Required when scope is MESSAGING_THREAD

Responses

Request samples

Content type
application/json
{
  • "scope": "FRIENDS",
  • "query": "string",
  • "scopeKey": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "scope": "FRIENDS",
  • "scopeKey": "string",
  • "query": "string",
  • "lastUsedAt": "2019-08-24T14:15:22Z"
}

Clear all recent searches for a scope

Authorizations:
bearerAuth
query Parameters
scope
required
string (SearchHistoryScope)
Enum: "FRIENDS" "MESSAGING" "MESSAGING_THREAD" "ALBUM" "LOCATION" "EXPENSE" "GIF"
scopeKey
string <= 64 characters

Responses

Response samples

Content type
application/json
{ }

Delete one recent search entry

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Heartbeat current location and list nearby users within 5km

Authorizations:
bearerAuth
Request Body schema: application/json
required
lat
required
number <double> [ -90 .. 90 ]
lon
required
number <double> [ -180 .. 180 ]

Responses

Request samples

Content type
application/json
{
  • "lat": -90,
  • "lon": -180
}

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

Leave nearby live index

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Update my profile bio

Sets the caller's profile bio. A blank or null bio clears it. The bio is at most 150 characters and is shown on the public profile.

Authorizations:
bearerAuth
Request Body schema: application/json
required
bio
string or null <= 150 characters

Profile bio. Blank or null clears it.

Responses

Request samples

Content type
application/json
{
  • "bio": "string"
}

Response samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "username": "string",
  • "displayName": "string",
  • "avatarUrl": "string",
  • "nickname": "string",
  • "subtitle": "string",
  • "friendStatus": "NONE",
  • "stats": {
    },
  • "online": true,
  • "lastSeenAt": "2019-08-24T14:15:22Z",
  • "bio": "string",
  • "activeNote": {
    }
}

Get 24h status notes feed

Returns the caller's active 24h status note (if any) and visible active notes from friends, ordered by unseen first then newest first.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "myNote": {
    },
  • "friendNotes": [
    ]
}

Create or replace my 24h status note

Replaces any existing active note for the caller with a new 24h status note containing text (<= 60 chars) and/or music clip.

Authorizations:
bearerAuth
Request Body schema: application/json
required
text
string or null <= 60 characters
visibility
string
Default: "FRIENDS"
Enum: "FRIENDS" "GROUPS" "SPECIFIC_USERS" "FRIENDS_EXCEPT"
allowedGroupIds
Array of strings <uuid> <= 100 items [ items <uuid > ]

Required when visibility is GROUPS.

allowedUserIds
Array of strings <uuid> <= 100 items [ items <uuid > ]

Required when visibility is SPECIFIC_USERS.

excludedUserIds
Array of strings <uuid> <= 100 items [ items <uuid > ]

Required when visibility is FRIENDS_EXCEPT.

object (NoteMusic)

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "visibility": "FRIENDS",
  • "allowedGroupIds": [
    ],
  • "allowedUserIds": [
    ],
  • "excludedUserIds": [
    ],
  • "music": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "username": "string",
  • "displayName": "string",
  • "nickname": "string",
  • "avatarUrl": "string",
  • "text": "string",
  • "visibility": "FRIENDS",
  • "allowedGroupIds": [
    ],
  • "allowedUserIds": [
    ],
  • "excludedUserIds": [
    ],
  • "music": {
    },
  • "seen": true,
  • "myReaction": "string",
  • "myReactionCount": 0,
  • "myReactions": {
    },
  • "viewCount": 0,
  • "reactionCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Delete my active 24h status note

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Mark a friend's status note as seen

Authorizations:
bearerAuth
path Parameters
noteId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

React to a status note

Authorizations:
bearerAuth
path Parameters
noteId
required
string <uuid>
Request Body schema: application/json
required
emoji
string or null <= 32 characters
count
integer or null >= 1

Responses

Request samples

Content type
application/json
{
  • "emoji": "string",
  • "count": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "username": "string",
  • "displayName": "string",
  • "nickname": "string",
  • "avatarUrl": "string",
  • "text": "string",
  • "visibility": "FRIENDS",
  • "allowedGroupIds": [
    ],
  • "allowedUserIds": [
    ],
  • "excludedUserIds": [
    ],
  • "music": {
    },
  • "seen": true,
  • "myReaction": "string",
  • "myReactionCount": 0,
  • "myReactions": {
    },
  • "viewCount": 0,
  • "reactionCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Remove my reaction from a status note

Authorizations:
bearerAuth
path Parameters
noteId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "username": "string",
  • "displayName": "string",
  • "nickname": "string",
  • "avatarUrl": "string",
  • "text": "string",
  • "visibility": "FRIENDS",
  • "allowedGroupIds": [
    ],
  • "allowedUserIds": [
    ],
  • "excludedUserIds": [
    ],
  • "music": {
    },
  • "seen": true,
  • "myReaction": "string",
  • "myReactionCount": 0,
  • "myReactions": {
    },
  • "viewCount": 0,
  • "reactionCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Get viewers and reactions for my active status note

Authorizations:
bearerAuth
path Parameters
noteId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "reactionCounts": {
    }
}

Get public user profile

Returns a user's profile and aggregate stats. For another user, the response also includes their relationship to the caller; for the caller's own profile, friendStatus is NONE. online and lastSeenAt are included only for the caller's own profile or when friendStatus is FRIENDS.

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "username": "string",
  • "displayName": "string",
  • "avatarUrl": "string",
  • "nickname": "string",
  • "subtitle": "string",
  • "friendStatus": "NONE",
  • "stats": {
    },
  • "online": true,
  • "lastSeenAt": "2019-08-24T14:15:22Z",
  • "bio": "string",
  • "activeNote": {
    }
}

Get friend payment profile

Returns payment QR/bank details for a friend. Forbidden for self, strangers, or blocked users.

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "qrImageUrl": "string",
  • "accountName": "string",
  • "accountNumber": "string",
  • "bankName": "string",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Suggest friends for @mention

Authorizations:
bearerAuth
query Parameters
q
required
string
limit
integer [ 1 .. 20 ]
Default: 10

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Public profile landing by username

path Parameters
username
required
string [ 3 .. 50 ] characters ^[a-zA-Z0-9_.]+$

Responses

Response samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "username": "string",
  • "displayName": "string",
  • "avatarUrl": "string",
  • "friendCount": 0,
  • "postCount": 0
}

Social Friendships

Friend requests, friendships, blocks

Send friend request by username

Authorizations:
bearerAuth
Request Body schema: application/json
required
username
required
string [ 3 .. 100 ] characters
message
string <= 280 characters

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "requesterId": "ba828041-f5bf-46f6-bf7c-22eccb01f2a4",
  • "addresseeId": "a1cd7f0d-5c75-486c-a8c9-7a3b2c0ec90f",
  • "status": "string",
  • "message": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "addresseeUsername": "string",
  • "addresseeDisplayName": "string"
}

Send friend request by personal QR payload

Authorizations:
bearerAuth
Request Body schema: application/json
required
qrPayload
required
string

Base64url JSON from POST /v1/social/qr/me (personal QR envelope)

message
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "qrPayload": "string",
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "requesterId": "ba828041-f5bf-46f6-bf7c-22eccb01f2a4",
  • "addresseeId": "a1cd7f0d-5c75-486c-a8c9-7a3b2c0ec90f",
  • "status": "string",
  • "message": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "addresseeUsername": "string",
  • "addresseeDisplayName": "string"
}

Accept incoming friend request

Authorizations:
bearerAuth
path Parameters
requestId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "friendshipId": "6dce0ec7-4364-4dbf-8496-4270437671d8",
  • "userAId": "6b5bf80f-ce93-4ea5-a0cc-caf76f4c6268",
  • "userBId": "68e1ced2-f434-4102-9b8e-7a5a86b1de50",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Reject incoming friend request

Authorizations:
bearerAuth
path Parameters
requestId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Cancel outgoing friend request

Authorizations:
bearerAuth
path Parameters
requestId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

List incoming friend requests

Authorizations:
bearerAuth
query Parameters
page
integer >= 0
Default: 0
size
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{ }

List outgoing friend requests

Authorizations:
bearerAuth
query Parameters
page
integer >= 0
Default: 0
size
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

List friends

Authorizations:
bearerAuth
query Parameters
page
integer >= 0
Default: 0
size
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

List close friends

One-way list of people the caller marked as close friends. The other user is not notified and is not added in reverse.

Authorizations:
bearerAuth
query Parameters
page
integer >= 0
Default: 0
size
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

Remove friend

Authorizations:
bearerAuth
path Parameters
friendUserId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Add or remove a close friend

Marks or unmarks an active friend as a close friend for the caller only. Requires an ACTIVE friendship. Idempotent.

Authorizations:
bearerAuth
path Parameters
friendUserId
required
string <uuid>
Request Body schema: application/json
required
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "friendUserId": "6501e41b-0761-451a-aad4-339fc41162aa",
  • "enabled": true
}

Set friend nickname (visible to caller only)

Authorizations:
bearerAuth
path Parameters
friendUserId
required
string <uuid>
Request Body schema: application/json
required
nickname
string or null <= 80 characters

Responses

Request samples

Content type
application/json
{
  • "nickname": "string"
}

Response samples

Content type
application/json
{
  • "friendId": "4bd6e55f-1d02-40eb-85a5-4e8b566403a4",
  • "username": "string",
  • "displayName": "string",
  • "avatarUrl": "http://example.com",
  • "nickname": "string",
  • "friendsSince": "2019-08-24T14:15:22Z"
}

List blocked users

Authorizations:
bearerAuth
query Parameters
page
integer >= 0
Default: 0
size
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

Block a user

Authorizations:
bearerAuth
Request Body schema: application/json
required
userId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Unblock a user

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Social Groups

Groups and membership

List my groups

Authorizations:
bearerAuth
query Parameters
page
integer >= 0
Default: 0
size
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

Create a group

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
description
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "avatarUrl": "http://example.com",
  • "ownerId": "4d206909-730f-409a-88f6-dcfaa8fc28cc",
  • "createdAt": "2019-08-24T14:15:22Z"
}

List pending group invitations received by current user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Accept a group invitation

Authorizations:
bearerAuth
path Parameters
invitationId
required
string <uuid>

Group member row ID of the invitation

Responses

Response samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "membershipId": "8072cc74-4782-4f2c-827c-699c48ce2092",
  • "status": "ACTIVE"
}

Reject a group invitation

Authorizations:
bearerAuth
path Parameters
invitationId
required
string <uuid>

Group member row ID of the invitation

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Get group details

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "avatarUrl": "http://example.com",
  • "ownerId": "4d206909-730f-409a-88f6-dcfaa8fc28cc",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Rename or update group description

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
description
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "avatarUrl": "http://example.com",
  • "ownerId": "4d206909-730f-409a-88f6-dcfaa8fc28cc",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Delete group (owner)

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Update group avatar URL (any active member)

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
Request Body schema: application/json
required
avatarUrl
required
string <uri> <= 500 characters

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "avatarUrl": "http://example.com",
  • "ownerId": "4d206909-730f-409a-88f6-dcfaa8fc28cc",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Transfer group ownership

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
Request Body schema: application/json
required
newOwnerId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "newOwnerId": "7794d3b0-c388-4512-b96a-362c09616997"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "avatarUrl": "http://example.com",
  • "ownerId": "4d206909-730f-409a-88f6-dcfaa8fc28cc",
  • "createdAt": "2019-08-24T14:15:22Z"
}

List group members

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
query Parameters
status
string
Enum: "ACTIVE" "PENDING" "REMOVED"
page
integer >= 0
Default: 0
size
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

Invite friends to group

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
Request Body schema: application/json
required
userIds
required
Array of strings <uuid> [ 1 .. 50 ] items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "userIds": [
    ]
}

Response samples

Content type
application/json
{
  • "invited": [
    ],
  • "skipped": [
    ]
}

Approve pending member (owner)

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
memberRowId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "username": "string",
  • "displayName": "string",
  • "avatarUrl": "http://example.com",
  • "role": "string",
  • "status": "string",
  • "invitedAt": "2019-08-24T14:15:22Z",
  • "joinedAt": "2019-08-24T14:15:22Z"
}

Reject pending member (owner)

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
memberRowId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Remove member from group (owner)

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
memberRowId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Leave group

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Lookup group by invite code or QR payload

Prefer this over GET when the code is a server QR payload. The payload is sent in the JSON body so it is not altered by query-string encoding.

Authorizations:
bearerAuth
Request Body schema: application/json
required
code
required
string

Invite code or server-issued group QR payload

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "avatarUrl": "http://example.com",
  • "memberCount": 0,
  • "inviteCode": "string",
  • "isMember": true,
  • "pendingApproval": true,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Lookup group by invite code

Authorizations:
bearerAuth
query Parameters
code
required
string

Group invite code

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "avatarUrl": "http://example.com",
  • "memberCount": 0,
  • "inviteCode": "string",
  • "isMember": true,
  • "pendingApproval": true,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Social Invitations

Invite codes and group join flows

Join group by invite code

Authorizations:
bearerAuth
Request Body schema: application/json
required
code
required
string [ 8 .. 16 ] characters

Responses

Request samples

Content type
application/json
{
  • "code": "stringst"
}

Response samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "membershipId": "8072cc74-4782-4f2c-827c-699c48ce2092",
  • "status": "ACTIVE"
}

Join group by QR payload

Authorizations:
bearerAuth
Request Body schema: application/json
required
qrPayload
required
string

Responses

Request samples

Content type
application/json
{
  • "qrPayload": "string"
}

Response samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "membershipId": "8072cc74-4782-4f2c-827c-699c48ce2092",
  • "status": "ACTIVE"
}

Get active group invite code

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "code": "string",
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "issuedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "maxUses": 0,
  • "usedCount": 0
}

Generate group invite code

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
Request Body schema: application/json
expiresAt
string <date-time>
maxUses
integer [ 1 .. 1000 ]

Responses

Request samples

Content type
application/json
{
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "maxUses": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "code": "string",
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "issuedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "maxUses": 0,
  • "usedCount": 0
}

Revoke group invite code

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
invitationId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Generate group join QR

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
Request Body schema: application/json
ttlSeconds
integer [ 60 .. 604800 ]

Responses

Request samples

Content type
application/json
{
  • "ttlSeconds": 60
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "payload": "string",
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "issuedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Revoke group QR

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
qrId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Social QR

Personal and group QR identities

Generate personal QR identity

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "payload": "string",
  • "version": 0,
  • "issuedAt": "2019-08-24T14:15:22Z"
}

Revoke personal QR (rotate)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Media

Presigned uploads to Cloudflare R2 (avatars)

Initiate presigned upload

Creates a PENDING media row and returns a presigned PUT URL for Cloudflare R2. Client uploads bytes directly to R2, then calls complete.

Authorizations:
bearerAuth
Request Body schema: application/json
required
purpose
required
string
Enum: "USER_AVATAR" "USER_PAYMENT_QR" "GROUP_AVATAR" "GROUP_CUSTOM_EMOJI" "USER_CUSTOM_EMOJI" "POST_IMAGE" "POST_VIDEO" "COMMENT_ATTACHMENT"
contentType
required
string
contentLength
required
integer <int64> >= 1
object

Responses

Request samples

Content type
application/json
{
  • "purpose": "USER_AVATAR",
  • "contentType": "string",
  • "contentLength": 1,
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "uploadId": "ef523ba8-509e-47af-8e2c-5fa751596497",
  • "presignedUrl": "string",
  • "requiredHeaders": {
    },
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Complete presigned upload

Verifies object on R2 (HeadObject) and marks media READY.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
etag
string or null

Responses

Request samples

Content type
application/json
{
  • "etag": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "string",
  • "thumbnailUrl": "string",
  • "sizeBytes": 0
}

Delete media

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

List active camera filters

Returns filter catalog metadata (LUT, matrix, AR) for mobile clients.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get filter by id

path Parameters
filterId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "name": "string",
  • "type": "LUT",
  • "thumbnailUrl": "string",
  • "assetUrl": "string",
  • "version": 0,
  • "minAppVersion": "string"
}

Expenses

Bill splits, settlements, and debt balances

Public bill invite landing payload

path Parameters
token
required
string

Responses

Response samples

Content type
application/json
{
  • "kind": "participant",
  • "postId": "1d33c5d7-f0cb-41cc-a647-907f16832fc3",
  • "creatorDisplayName": "string",
  • "description": "string",
  • "currency": "string",
  • "amount": "string",
  • "guestDisplayName": "string",
  • "maskedPhone": "string",
  • "expiredOrClaimed": true,
  • "claimed": true,
  • "paymentStatus": "UNPAID",
  • "canPayWithoutApp": true,
  • "participants": [
    ],
  • "qrImageUrl": "string",
  • "maskedEmail": "string"
}

Report guest payment with 1–3 proof photos (invite token is sufficient)

path Parameters
token
required
string
Request Body schema: multipart/form-data
required
files
required
Array of strings <binary> [ 1 .. 3 ] items [ items <binary > ]
note
string <= 500 characters

Responses

Response samples

Content type
application/json
{
  • "splitId": "de34ca5c-3404-42f1-84f9-e8d3dd216a8f",
  • "paymentStatus": "string",
  • "commentId": "ee0469af-2fa1-4b7e-b5f1-8e711a95821b"
}

Claim a guest split after sign-in

Authorizations:
bearerAuth
path Parameters
token
required
string
Request Body schema: application/json
optional
splitId
string <uuid>

Required when claiming via a table QR token

Responses

Request samples

Content type
application/json
{
  • "splitId": "de34ca5c-3404-42f1-84f9-e8d3dd216a8f"
}

Response samples

Content type
application/json
{
  • "expenseId": "a2142719-090a-410b-ad70-ea5efeb1c9dc",
  • "postId": "1d33c5d7-f0cb-41cc-a647-907f16832fc3",
  • "splitId": "de34ca5c-3404-42f1-84f9-e8d3dd216a8f"
}

Get expense linked to a feed post

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "totalAmount": "string",
  • "currency": "string",
  • "paidBy": {
    },
  • "splits": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "postId": "1d33c5d7-f0cb-41cc-a647-907f16832fc3",
  • "category": "string",
  • "status": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "settledAt": "2019-08-24T14:15:22Z",
  • "tableInviteUrl": "string",
  • "closedAt": "2019-08-24T14:15:22Z",
  • "closedReason": "string"
}

List personal pay links for pending guests

Returns one claim URL per guest split that still has no Splick user. Only the bill creator or payer can call this. Other callers receive 404. The URL is a bearer secret; do not log it.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{
  • "invites": [
    ]
}

Get or rotate table QR invite URL

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

rotate
boolean
Default: false

Responses

Response samples

Content type
application/json
{
  • "tableUrl": "string"
}

List expenses

Returns expenses visible to the authenticated user for the requested page. Response is a JSON array (iOS compatibility); use page and limit query params for paging. Prefer keyset pagination via optional cursor (opaque, from the previous page's last item createdAt + id). When cursor is set, page is ignored. First page: omit cursor (or page=0). hasMore = response length equals limit.

Authorizations:
bearerAuth
query Parameters
page
integer >= 0
Default: 0
limit
integer [ 1 .. 100 ]
Default: 20
cursor
string

Opaque keyset cursor from the previous page (Base64 of createdAt|expenseId). When present, page is ignored.

groupId
string <uuid>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create expense

Authorizations:
bearerAuth
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "totalAmount": "string",
  • "currency": "string",
  • "paidBy": {
    },
  • "splits": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "postId": "1d33c5d7-f0cb-41cc-a647-907f16832fc3",
  • "category": "string",
  • "status": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "settledAt": "2019-08-24T14:15:22Z",
  • "tableInviteUrl": "string",
  • "closedAt": "2019-08-24T14:15:22Z",
  • "closedReason": "string"
}

List net debt balances

Authorizations:
bearerAuth
query Parameters
page
integer >= 0
Default: 0
limit
integer [ 1 .. 100 ]
Default: 20
groupId
string <uuid>
from
string <date-time>
to
string <date-time>
direction
string
Default: "ALL"
Enum: "ALL" "OWED" "OWES"
status
string
Default: "OPEN"
Enum: "OPEN" "SETTLED"

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": 0,
  • "limit": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "nextCursor": "string"
}

Monthly settled income and expenditure summary

Returns settled cash-flow totals for the authenticated user over the last N calendar months (including the current month).

  • totalSettledReceived: amounts paid back to the actor (actor was the payer)
  • totalSettledPaid: amounts the actor paid to others (actor was the debtor) Missing months are filled with zero amounts. Prefers VND when multiple currencies exist.
Authorizations:
bearerAuth
query Parameters
months
integer [ 1 .. 24 ]
Default: 12

Number of months to include (1–24), including the current month.

Responses

Response samples

Content type
application/json
{
  • "currency": "VND",
  • "currentMonth": {
    },
  • "months": [
    ]
}

Expense overview for the authenticated user

Lightweight BFF payload for the Overview tab: net balance with highlighted counterparties, action items that need attention, recent expenses, and this-month vs last-month spending.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "balance": {
    },
  • "needsAttention": {
    },
  • "recentExpenses": [
    ],
  • "totalSpending": {
    }
}

Spending trend and category breakdown

Returns the actor's share of spending as a time series (line/area chart) and category totals (donut chart). WEEK uses weekly buckets for the last 4 weeks. MONTH uses monthly buckets from the start of the lookback window.

Authorizations:
bearerAuth
query Parameters
period
string
Default: "MONTH"
Enum: "WEEK" "MONTH"
months
integer [ 1 .. 12 ]
Default: 3

Lookback window in calendar months for MONTH period (1–12). Ignored for WEEK.

Responses

Response samples

Content type
application/json
{
  • "trend": [
    ],
  • "categories": [
    ],
  • "currency": "string"
}

Group expense cards for the authenticated user

Groups that have expenses involving the actor, with group spending, amount the actor paid, and the actor's net balance in each group.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ]
}

List expenses owed by a guest who has no Splick account

Authorizations:
bearerAuth
query Parameters
guestKey
required
string

guestKey from a debt balance row

page
integer >= 0
Default: 0
limit
integer [ 1 .. 100 ]
Default: 20
cursor
string

Opaque keyset cursor from the previous page (Base64 of createdAt|expenseId). When present, page is ignored.

status
string
Default: "ALL"
Enum: "OPEN" "SETTLED" "ALL"

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": 0,
  • "limit": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "nextCursor": "string"
}

Net debt with a guest who has no Splick account

Authorizations:
bearerAuth
query Parameters
guestKey
required
string

Responses

Response samples

Content type
application/json
{
  • "counterparty": {
    },
  • "actorOwesTotal": "150000",
  • "counterpartyOwesTotal": "50000",
  • "netAmount": "100000",
  • "netDirection": "ACTOR_OWES",
  • "currency": "string",
  • "unpaidSplitCount": 0,
  • "expensesInvolved": 0,
  • "pendingSettlement": {
    }
}

List expenses directly involving a counterparty

Returns canonical expenses across all groups where the authenticated user and counterparty are the direct debtor and creditor. Prefer keyset pagination via optional cursor. When cursor is set, page is ignored and totalElements/totalPages may be zero. nextCursor is present when another page may exist.

Authorizations:
bearerAuth
path Parameters
counterpartyId
required
string <uuid>
query Parameters
page
integer >= 0
Default: 0
limit
integer [ 1 .. 100 ]
Default: 20
cursor
string

Opaque keyset cursor from the previous page (Base64 of createdAt|expenseId). When present, page is ignored.

status
string
Default: "OPEN"
Enum: "OPEN" "SETTLED" "ALL"

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": 0,
  • "limit": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "nextCursor": "string"
}

Get net debt with a counterparty

Returns a single-currency netting summary. Responds with 409 when open debts span multiple currencies.

Authorizations:
bearerAuth
path Parameters
counterpartyId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "counterparty": {
    },
  • "actorOwesTotal": "150000",
  • "counterpartyOwesTotal": "50000",
  • "netAmount": "100000",
  • "netDirection": "ACTOR_OWES",
  • "currency": "string",
  • "unpaidSplitCount": 0,
  • "expensesInvolved": 0,
  • "pendingSettlement": {
    }
}

Submit bulk settlement evidence

Snapshots all currently open direct splits between the actor and counterparty. For each snapshot split that still has a live SHARE_BILL postId and is not already PENDING_APPROVAL/PAID, the service creates a feed EVIDENCE comment with the submitted screenshots and links payment_evidence_submissions.bulk_settlement_id. Splits remain open until the creditor approves per-post evidence or approves this bulk settlement.

Authorizations:
bearerAuth
path Parameters
counterpartyId
required
string <uuid>
Request Body schema: application/json
required
evidenceUrl
string <uri> <= 2048 characters ^https://

Legacy single evidence URL. Prefer evidenceUrls when submitting multiple screenshots.

evidenceUrls
Array of strings <uri> [ 1 .. 3 ] items [ items <uri > <= 2048 characters ^https:// ]

Transfer screenshots (1–3 HTTPS URLs). Required unless evidenceUrl is provided.

note
string or null <= 500 characters

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "debtorUserId": "ba83c7c7-c6ba-4ac9-9f4c-a9dfbd672734",
  • "creditorUserId": "bf5caf55-7654-430b-9e9c-3d43708dac8c",
  • "amount": "string",
  • "currency": "string",
  • "evidenceUrl": "http://example.com",
  • "evidenceUrls": [],
  • "note": "string",
  • "status": "PENDING_APPROVAL",
  • "rejectReason": "string",
  • "splitCount": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "reviewedAt": "2019-08-24T14:15:22Z"
}

Approve a bulk settlement

Only the snapshot creditor may approve. Approval marks snapshot splits paid, approves any still-pending payment_evidence_submissions linked by bulk_settlement_id, and cascades APPROVED status onto the related feed EVIDENCE comments.

Authorizations:
bearerAuth
path Parameters
settlementId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "debtorUserId": "ba83c7c7-c6ba-4ac9-9f4c-a9dfbd672734",
  • "creditorUserId": "bf5caf55-7654-430b-9e9c-3d43708dac8c",
  • "amount": "string",
  • "currency": "string",
  • "evidenceUrl": "http://example.com",
  • "evidenceUrls": [],
  • "note": "string",
  • "status": "PENDING_APPROVAL",
  • "rejectReason": "string",
  • "splitCount": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "reviewedAt": "2019-08-24T14:15:22Z"
}

Reject a bulk settlement

Only the snapshot creditor may reject. Split state is not changed.

Authorizations:
bearerAuth
path Parameters
settlementId
required
string <uuid>
Request Body schema: application/json
required
reason
string or null <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "debtorUserId": "ba83c7c7-c6ba-4ac9-9f4c-a9dfbd672734",
  • "creditorUserId": "bf5caf55-7654-430b-9e9c-3d43708dac8c",
  • "amount": "string",
  • "currency": "string",
  • "evidenceUrl": "http://example.com",
  • "evidenceUrls": [],
  • "note": "string",
  • "status": "PENDING_APPROVAL",
  • "rejectReason": "string",
  • "splitCount": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "reviewedAt": "2019-08-24T14:15:22Z"
}

Get expense by id

Authorizations:
bearerAuth
path Parameters
expenseId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "totalAmount": "string",
  • "currency": "string",
  • "paidBy": {
    },
  • "splits": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "postId": "1d33c5d7-f0cb-41cc-a647-907f16832fc3",
  • "category": "string",
  • "status": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "settledAt": "2019-08-24T14:15:22Z",
  • "tableInviteUrl": "string",
  • "closedAt": "2019-08-24T14:15:22Z",
  • "closedReason": "string"
}

Update expense

Blocked with 409 EXPENSE_LOCKED when linked feed post has interactions.

Authorizations:
bearerAuth
path Parameters
expenseId
required
string <uuid>
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "totalAmount": "string",
  • "currency": "string",
  • "paidBy": {
    },
  • "splits": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "postId": "1d33c5d7-f0cb-41cc-a647-907f16832fc3",
  • "category": "string",
  • "status": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "settledAt": "2019-08-24T14:15:22Z",
  • "tableInviteUrl": "string",
  • "closedAt": "2019-08-24T14:15:22Z",
  • "closedReason": "string"
}

Delete expense

Authorizations:
bearerAuth
path Parameters
expenseId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Mark expense split as paid

Authorizations:
bearerAuth
path Parameters
expenseId
required
string <uuid>
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "totalAmount": "string",
  • "currency": "string",
  • "paidBy": {
    },
  • "splits": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "postId": "1d33c5d7-f0cb-41cc-a647-907f16832fc3",
  • "category": "string",
  • "status": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "settledAt": "2019-08-24T14:15:22Z",
  • "tableInviteUrl": "string",
  • "closedAt": "2019-08-24T14:15:22Z",
  • "closedReason": "string"
}

Feed

Social feed posts, reactions, and comments

Public post Open Graph and web landing preview

path Parameters
postId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "postId": "1d33c5d7-f0cb-41cc-a647-907f16832fc3",
  • "authorUsername": "string",
  • "authorDisplayName": "string",
  • "authorAvatarUrl": "string",
  • "caption": "string",
  • "checkInPlace": "string",
  • "previewImageUrl": "string",
  • "mediaType": "string",
  • "widthPx": 0,
  • "heightPx": 0,
  • "feedKind": "string",
  • "createdAt": "2019-08-24T14:15:22Z"
}

List feed posts

Returns visible feed posts as a JSON array for iOS compatibility. Use page and limit for paging. When authorId is provided, only posts authored by that user are returned, while the same audience visibility rules still apply. List cards omit the full reactions array ([]); use reactionCount, reactorCount, and reactionPreview (at most 3 users, actor pinned when they reacted). Open GET /v1/feed/posts/{postId}/reactions for the full grouped list.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

authorId
string <uuid>

Optional author UUID. Filters the feed to posts by this author without bypassing the authenticated actor's normal visibility rules.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Count posts newer than the client's feed head

Lightweight poll for the home-feed "N new posts" pill. Returns how many visible posts authored by others sort strictly ahead of (afterCreatedAt, afterId) under created_at DESC, id DESC. Does not hydrate post bodies. Count is capped at 99. Own posts are excluded. Hidden posts are excluded.

Authorizations:
bearerAuth
query Parameters
afterCreatedAt
required
string <date-time>

Created-at of the newest post currently shown at the top of the client's feed.

afterId
required
string <uuid>

Id of that same head post (tie-break with afterCreatedAt).

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

List photo album

Returns a flat, paginated list of image and video media items sorted newest first. Default view shows own posts and friends' posts. Optional filters: authorId (repeatable; self or friend), groupId (repeatable; posts tagged with any selected group; caller must be an active member of each), q (caption search, min 1 char), feedKind (checkIn for moments, shareBill for bill-split posts). When both authorId and groupId are set, matching photos from either filter are returned (OR). Use cursor for keyset pagination; when cursor is sent the response is a wrapper with nextCursor. Image URLs are stable CDN links — clients may cache bytes by URL across filter changes.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

limit
integer [ 1 .. 100 ]
Default: 50
authorId
Array of strings <uuid> <= 50 items [ items <uuid > ]

Repeat to filter by multiple authors (OR). Each id must be self or a friend.

groupId
Array of strings <uuid> <= 50 items [ items <uuid > ]

Repeat to filter by multiple groups (OR). Caller must be an active member of each.

q
string [ 1 .. 100 ] characters
feedKind
string
Enum: "checkIn" "shareBill"

Filter by post kind. Omit for all photos.

cursor
string

Responses

Response samples

Content type
application/json
Example
[ ]

Host transfer details for a bill participant

Returns the bill host payment profile (QR and bank account) so a participant can transfer money before uploading proof. Caller must be the host or a person on the bill. configured is false when the host has not saved transfer details.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "qrImageUrl": "string",
  • "accountName": "string",
  • "accountNumber": "string",
  • "bankName": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "configured": true
}

Splick Bot profile counters

Live counters for the Splick Bot profile. reminderCount is the number of people on every bill-split post. paidCount is how many of those people have a paid expense split. startedAt is the earlier of the first user account and the first post, used as the bot's experience start.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "reminderCount": 0,
  • "paidCount": 0,
  • "startedAt": "2019-08-24T14:15:22Z"
}

Get streak summary

Returns the live posting streak and whether the user already posted today in their profile IANA time zone (default Asia/Ho_Chi_Minh). The streak is consecutive calendar days with at least one IMAGE or VIDEO post. If the user has not posted yet today, yesterday's run still counts until that local day ends without a post. Missing a full calendar day resets the streak to 0.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "currentStreak": 7,
  • "hasTodayPhoto": true,
  • "canRestore": false,
  • "recoverableStreak": 12,
  • "restoresRemaining": 3
}

Restore a broken posting streak

Restores the posting streak that broke at the start of a missed calendar day, if the request is still inside a 48-hour window in the user's IANA time zone and the user has remaining monthly restores (3 per calendar month, reset on the 1st). After a successful restore the live streak equals the length immediately before the break, even if the user has not posted today.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "currentStreak": 7,
  • "hasTodayPhoto": true,
  • "canRestore": false,
  • "recoverableStreak": 12,
  • "restoresRemaining": 3
}

Get streak leaderboard

Ranks the caller among friends or all users by the live posting streak or by best streak. Friends includes the caller and every active friend, including people whose streak is 0. Global omits users whose live streak and best streak are both 0, and omits users blocked in either direction. Sort defaults to the live streak. When that streak is equal, the person with more image or video posts ranks higher. When the streak and the post count are both equal, those people share a rank. The response contains at most 25 people. The caller's row is always returned in viewer; viewer.rank is null on the global board when the caller has no live streak and no best streak. nextCursor is always null.

Authorizations:
bearerAuth
query Parameters
scope
required
string
Enum: "friends" "global"
sort
string
Default: "current"
Enum: "current" "best"
limit
integer [ 1 .. 25 ]
Default: 25
cursor
string

Accepted for older clients. The board always returns the top 25, so this value does not move the window and nextCursor is null.

Responses

Response samples

Content type
application/json
{
  • "viewer": {
    },
  • "entries": [
    ],
  • "nextCursor": "string"
}

Get streak calendar for a month

Returns one entry per calendar day in the requested month in the user's IANA time zone. Days where the authenticated user published at least one IMAGE or VIDEO post include firstPhotoUrl, firstThumbnailUrl, and photoCount > 0. A video day's cover is its thumbnail when one exists. Empty days have photoCount: 0 and null URLs. Days are ordered newest-first (end of month → start of month).

Authorizations:
bearerAuth
query Parameters
year
required
integer >= 2020
Example: year=2026
month
required
integer [ 1 .. 12 ]
Example: month=6

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get photos for a streak day

Returns all IMAGE and VIDEO media items the authenticated user published on the given calendar date in the user's IANA time zone, ordered by post creation time and sort_order. Used to populate the day-detail carousel in the streak tab.

Authorizations:
bearerAuth
path Parameters
date
required
string <date>
Example: 2026-06-12

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search location suggestions

Authorizations:
bearerAuth
query Parameters
q
required
string <= 100 characters
limit
integer [ 1 .. 20 ]
Default: 10
lat
number <double> [ -90 .. 90 ]
lon
number <double> [ -180 .. 180 ]

Responses

Response samples

Content type
application/json
{
  • "locations": [
    ]
}

Nearby places for check-in

Authorizations:
bearerAuth
query Parameters
lat
required
number <double> [ -90 .. 90 ]
lon
required
number <double> [ -180 .. 180 ]
radius
integer [ 1 .. 10000 ]
Default: 2000
limit
integer [ 1 .. 20 ]
Default: 10
page
integer [ 0 .. 10 ]
Default: 0

Zero-based page. Results stay ordered from nearest to farthest inside the radius.

Responses

Response samples

Content type
application/json
{
  • "locations": [
    ]
}

Check-in count for a place

Authorizations:
bearerAuth
path Parameters
placeId
required
string^[A-Za-z0-9_-]{2,128}$

Responses

Response samples

Content type
application/json
{
  • "placeId": "string",
  • "checkInCount": 0
}

How many posts use a music track

Authorizations:
bearerAuth
query Parameters
provider
required
string^[A-Za-z0-9_.:-]{1,32}$
externalId
required
string^[A-Za-z0-9_.:-]{1,128}$

Responses

Response samples

Content type
application/json
{
  • "provider": "string",
  • "externalId": "string",
  • "useCount": 0
}

Create feed post

Authorizations:
bearerAuth
Request Body schema: application/json
required
caption
string <= 2000 characters
groupId
string or null <uuid>

First tagged social group (legacy). Combined with groupIds.

groupIds
Array of strings or null <uuid> <= 10 items [ items <uuid > ]

Additional or complete list of tagged social groups (max 10 unique).

feedKind
string
Enum: "check_in" "share_bill"
checkInPlace
string or null <= 500 characters
object (PostLocationResponse)
Array of objects (CreatePostMediaItemRequest) [ 1 .. 10 ] items

Up to 10 media items (images and videos, mixed).

companionIds
Array of strings <uuid> [ items <uuid > ]
mediaId
string or null <uuid>
object (ShareBillRequest)
companionGroupName
string or null <= 200 characters

Display name of the social group tagged on a share-bill post. Not a feed groupId.

object (PostAudienceRequest)

Responses

Request samples

Content type
application/json
{
  • "caption": "string",
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "groupIds": [
    ],
  • "feedKind": "check_in",
  • "checkInPlace": "string",
  • "location": {
    },
  • "mediaItems": [
    ],
  • "companionIds": [
    ],
  • "mediaId": "5a8ffac5-2288-485d-b463-90c3cd9941ad",
  • "billSplit": {
    },
  • "companionGroupName": "string",
  • "audience": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "author": {
    },
  • "mediaItems": [
    ],
  • "caption": "string",
  • "mentions": [
    ],
  • "reactions": [
    ],
  • "reactionCount": 0,
  • "reactorCount": 0,
  • "reactionPreview": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "groupIds": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "editedAt": "2019-08-24T14:15:22Z",
  • "companions": [
    ],
  • "feedKind": "string",
  • "checkInPlace": "string",
  • "location": {
    },
  • "audience": {
    },
  • "billSplit": {
    },
  • "comments": [
    ],
  • "commentCount": 0,
  • "viewCount": 0,
  • "viewers": [
    ]
}

Batch record post views

Records views for up to 20 posts in a single call. Posts that are deleted, inaccessible, or authored by the caller are silently skipped. Returns the assembled view for each successfully recorded post.

Authorizations:
bearerAuth
Request Body schema: application/json
required
postIds
required
Array of strings <uuid> [ 1 .. 20 ] items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "postIds": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Get feed post

Records a view for the authenticated viewer (except author). Returns full comments and viewers. Reaction rows are omitted (reactions: []); use reactionPreview / counts on the card, or GET /v1/feed/posts/{postId}/reactions for the full grouped list. Visibility follows audience plus ongoing access for post companions and bill-split participants, including after the viewer unfriends the author.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "author": {
    },
  • "mediaItems": [
    ],
  • "caption": "string",
  • "mentions": [
    ],
  • "reactions": [
    ],
  • "reactionCount": 0,
  • "reactorCount": 0,
  • "reactionPreview": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "groupIds": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "editedAt": "2019-08-24T14:15:22Z",
  • "companions": [
    ],
  • "feedKind": "string",
  • "checkInPlace": "string",
  • "location": {
    },
  • "audience": {
    },
  • "billSplit": {
    },
  • "comments": [
    ],
  • "commentCount": 0,
  • "viewCount": 0,
  • "viewers": [
    ]
}

Update feed post

Author-only. Updates caption, media items, audience, and tagged companions. Snapshots the previous caption, media, audience, and companions into edit history before applying the change. Location and bill split are not editable. Omit audience or companionIds to leave that field unchanged.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
required
caption
string or null <= 2000 characters
required
Array of objects (CreatePostMediaItemRequest) [ 1 .. 10 ] items

Up to 10 media items (images and videos, mixed).

object (PostAudienceRequest)
companionIds
Array of strings or null <uuid> [ items <uuid > ]

Omit to keep current tagged friends. Empty list clears tags.

Responses

Request samples

Content type
application/json
{
  • "caption": "string",
  • "mediaItems": [
    ],
  • "audience": {
    },
  • "companionIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "author": {
    },
  • "mediaItems": [
    ],
  • "caption": "string",
  • "mentions": [
    ],
  • "reactions": [
    ],
  • "reactionCount": 0,
  • "reactorCount": 0,
  • "reactionPreview": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "groupIds": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "editedAt": "2019-08-24T14:15:22Z",
  • "companions": [
    ],
  • "feedKind": "string",
  • "checkInPlace": "string",
  • "location": {
    },
  • "audience": {
    },
  • "billSplit": {
    },
  • "comments": [
    ],
  • "commentCount": 0,
  • "viewCount": 0,
  • "viewers": [
    ]
}

Delete feed post

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Hide feed post for caller

Hides the post from the caller's feed only. Other viewers are unaffected. Idempotent when the post is already hidden.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Report feed post

Reports the post for moderation review and hides it from the caller's feed. Authors cannot report their own posts. Idempotent when the caller already reported the same post (existing report is left unchanged; hide is still applied). When reason is OTHER, note is required.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
required
reason
required
string (ReportPostReason)
Enum: "SPAM" "HARASSMENT" "HATE_SPEECH" "NUDITY" "VIOLENCE" "MISINFORMATION" "SCAM" "OTHER"

Why the caller is reporting the post

note
string or null <= 500 characters

Optional details; required when reason is OTHER

Responses

Request samples

Content type
application/json
{
  • "reason": "SPAM",
  • "note": "string"
}

Response samples

Content type
application/json
{ }

List feed post edit history

Previous post snapshots, newest first. Visible to anyone who can view the post. Includes caption, media, audience, and companions when those fields were captured. The live post is the current version and is not included.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List grouped reactions for a post

Returns all reactors grouped by user with per-emoji counts, sorted by total reaction count descending then userId. Same visibility rules as GET /v1/feed/posts/{postId}.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{
  • "reactionCount": 0,
  • "reactorCount": 0,
  • "items": [
    ]
}

Add reaction to post

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
required
emoji
required
string <= 64 characters

Responses

Request samples

Content type
application/json
{
  • "emoji": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "emoji": "string",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Remove reaction from post

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

List who viewed a post

Pages users who viewed the post (excluding the author), newest first. Only the post author may call this. viewCount is the total, which may exceed viewers.length.

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

page
integer >= 0
Default: 0
limit
integer [ 1 .. 100 ]
Default: 20

Viewers per page (1–100).

Responses

Response samples

Content type
application/json
{
  • "viewers": [
    ],
  • "page": 0,
  • "limit": 0,
  • "hasMore": true,
  • "viewCount": 0
}

List post comments

Pages top-level comments (parentCommentId is null) using page/limit. filter applies to roots only: COMMENTS (STANDARD), EVIDENCE, or ALL. Every descendant of a returned root is included in the same comments array, regardless of type. Soft-deleted comments are returned as tombstones (body null).

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

page
integer >= 0
Default: 0
limit
integer [ 1 .. 100 ]
Default: 20

Number of root comments per page (1–100). Children do not count toward limit.

filter
string
Default: "ALL"
Enum: "COMMENTS" "EVIDENCE" "ALL"

Responses

Response samples

Content type
application/json
{
  • "comments": [
    ],
  • "page": 0,
  • "limit": 1,
  • "hasMore": true
}

Add comment to post

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
required
body
string or null <= 4000 characters
parentCommentId
string or null <uuid>

Root comment to reply under (server flattens reply-to-reply).

Array of objects (CreateCommentAttachmentRequest)

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "parentCommentId": "32135137-e98b-4a27-b840-a577578abf9d",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Soft-delete a standard comment authored by the caller

Authorizations:
bearerAuth
path Parameters
commentId
required
string <uuid>
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Responses

Response samples

Content type
application/json
{ }

List reactors on a comment grouped by user

Returns unique reactors with their emoji counts, ordered by reaction count. Pass emoji to return only people who reacted with that emoji.

Authorizations:
bearerAuth
path Parameters
commentId
required
string <uuid>
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

emoji
string <= 64 characters

When set, only reactors who used this emoji are returned.

Responses

Response samples

Content type
application/json
{
  • "reactionCount": 0,
  • "reactorCount": 0,
  • "items": [
    ]
}

Toggle the caller's emoji on a comment

Adds the emoji, or removes it when the caller already reacted with the same emoji.

Authorizations:
bearerAuth
path Parameters
commentId
required
string <uuid>
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
required
emoji
required
string <= 64 characters

Responses

Request samples

Content type
application/json
{
  • "emoji": "string"
}

Response samples

Content type
application/json
{
  • "reaction": {
    }
}

Send bill split payment reminders

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
required
targetUserIds
Array of strings <uuid> [ items <uuid > ]

Optional subset of unpaid participants; omit to remind all unpaid

message
required
string <= 500 characters

Text included in the Splick Bot reminder comment

Array of objects (CreateCommentAttachmentRequest) <= 1 items

Optional GIF attached to the Splick Bot reminder comment

Responses

Request samples

Content type
application/json
{
  • "targetUserIds": [
    ],
  • "message": "string",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "sentCount": 0,
  • "skippedCount": 0
}

Submit payment evidence for a bill split

Authorizations:
bearerAuth
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
required
splitId
required
string <uuid>
message
string <= 500 characters
required
Array of objects (CreateCommentAttachmentRequest) non-empty

Responses

Request samples

Content type
application/json
{
  • "splitId": "de34ca5c-3404-42f1-84f9-e8d3dd216a8f",
  • "message": "string",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "evidenceId": "84c8ea22-9959-4357-9a32-7546d09a0037",
  • "commentId": "ee0469af-2fa1-4b7e-b5f1-8e711a95821b"
}

Approve payment evidence (post author only)

Authorizations:
bearerAuth
path Parameters
evidenceId
required
string <uuid>
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
optional
message
string <= 500 characters

Optional approve note. Server creates one evidence-moderation reply authored by the reviewer that tags the evidence submitter and appends this note (or a default thank-you when omitted).

Responses

Request samples

Content type
application/json
{
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Approve a bill split without payment evidence (post author only)

Authorizations:
bearerAuth
path Parameters
splitId
required
string <uuid>
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
optional
message
string <= 500 characters

Optional approve note. Server creates one evidence-moderation reply authored by the reviewer that tags the evidence submitter and appends this note (or a default thank-you when omitted).

Responses

Request samples

Content type
application/json
{
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Reject payment evidence (post author only)

Authorizations:
bearerAuth
path Parameters
evidenceId
required
string <uuid>
query Parameters
unresolved
string

Inserted by splick-docs prepare-openapi. The backend snapshot references a parameter that is not defined.

Request Body schema: application/json
required
reason
required
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Notifications

In-app notifications

List notifications

Authorizations:
bearerAuth
query Parameters
page
integer >= 0
Default: 0
size
integer [ 1 .. 100 ]
Default: 20
category
string
Enum: "ALL" "POSTS" "FRIENDS" "EXPENSES"

Optional filter by notification type group. ALL (default) returns every type. POSTS is feed/post/streak types. EXPENSES is bills, settlements, and payment evidence. FRIENDS is friend requests and group invites. Chat/group-message types appear only under ALL.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get unread notification count

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Get tab-bar badge counts by category

Returns badge counts for tab icons and the notification bell. notifications is unseen home-feed posts, friends is incoming pending friend requests, expenses is counterparties the current user still owes, and messages is unread conversations (one per peer or group), not the sum of unread messages. inbox is unread notification-inbox rows (excludes chat types). Opening the bell does not clear inbox; mark-read / mark-all-read does. Optimized for polling.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "notifications": 0,
  • "friends": 0,
  • "expenses": 0,
  • "messages": 0,
  • "inbox": 0,
  • "total": 0
}

Mark notification as read

Authorizations:
bearerAuth
path Parameters
notificationId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Mark notification as clicked

Marks the notification as read and clicked. Mobile clients call this when the user taps a notification item.

Authorizations:
bearerAuth
path Parameters
notificationId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Mark all notifications as read

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Mark notification inbox as seen

Records that the notification inbox was opened. Does not mark individual notifications as read and does not change the bell inbox unread count. Clients should not use this to clear the bell badge.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Register push device token (APNs or FCM)

Authorizations:
bearerAuth
Request Body schema: application/json
required
token
required
string <= 4096 characters
platform
required
string
Enum: "ios" "android"
bundleId
required
string

iOS bundle id or Android applicationId / package name.

environment
string
Enum: "sandbox" "production"

Required for iOS APNs. Optional for Android FCM.

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "platform": "ios",
  • "bundleId": "com.splick.app",
  • "environment": "sandbox"
}

Response samples

Content type
application/json
{ }

Unregister push device token

Authorizations:
bearerAuth
path Parameters
token
required
string <= 512 characters

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Messaging

Direct messaging (DM) between users

Inbox summary counts for conversation filters

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "unreadConversationCount": 0
}

List conversations

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0
limit
integer
Default: 20
type
string
Enum: "DIRECT" "GROUP"

Optional inbox filter by conversation type.

unreadOnly
boolean
Default: false

When true, return only conversations with unread messages.

closeFriendsOnly
boolean
Default: false

When true, return only DIRECT conversations whose peer the caller marked as a close friend. Empty when the caller has no close friends.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string",
  • "hasMore": true
}

Get or create a direct conversation with a user

Returns an existing direct conversation or creates one. Blocked users cannot start a new conversation (403).

Authorizations:
bearerAuth
Request Body schema: application/json
required
friendUserId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "friendUserId": "6501e41b-0761-451a-aad4-339fc41162aa"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "DIRECT",
  • "unreadCount": 0,
  • "peer": {
    },
  • "groupName": "string",
  • "groupAvatarUrl": "string",
  • "memberCount": 0,
  • "lastMessage": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "notificationsEnabled": true,
  • "notificationSound": "default",
  • "mutedUntil": "2019-08-24T14:15:22Z",
  • "leftAt": "2019-08-24T14:15:22Z",
  • "closeFriend": false,
  • "wallpaper": "string"
}

Delete chat for the current user

Hides the conversation and existing messages for the caller only. The other participants keep the thread. New messages after deletion bring the chat back to the inbox.

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

List messages in a conversation

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
query Parameters
page
integer
Default: 0
limit
integer
Default: 30
after
integer <int64>

Return messages with sequenceNo strictly greater than this value (forward sync).

before
integer <int64>

Return messages with sequenceNo strictly less than this value (older page).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string",
  • "hasMore": true
}

Send a message

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
Request Body schema: application/json
required
body
string <= 2000 characters
clientMessageId
required
string <uuid>
Array of objects (MessageAttachmentRequest) <= 5 items
replyToMessageId
string or null <uuid>

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "clientMessageId": "6751c24a-b4eb-49b8-a2cb-e2427e57e61b",
  • "attachments": [
    ],
  • "replyToMessageId": "666dd795-555f-462a-8c3b-fb8ab1fdc45f"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "conversationId": "ee6e55e8-45fe-4a3e-9bc8-4669f9fdf77a",
  • "senderId": "6b2f63ba-164c-48c9-87b1-690cee2b3da3",
  • "senderDisplayName": "string",
  • "body": "string",
  • "clientMessageId": "6751c24a-b4eb-49b8-a2cb-e2427e57e61b",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "sequenceNo": 0,
  • "editedAt": "2019-08-24T14:15:22Z",
  • "recalled": false,
  • "reactions": [
    ],
  • "status": "sent",
  • "attachments": [
    ],
  • "replyPreview": {
    },
  • "type": "USER",
  • "senderBubbleTheme": "rat"
}

Edit a message body (sender only, within 5 minutes)

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
messageId
required
string <uuid>
Request Body schema: application/json
required
body
required
string [ 1 .. 2000 ] characters

Responses

Request samples

Content type
application/json
{
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "conversationId": "ee6e55e8-45fe-4a3e-9bc8-4669f9fdf77a",
  • "senderId": "6b2f63ba-164c-48c9-87b1-690cee2b3da3",
  • "senderDisplayName": "string",
  • "body": "string",
  • "clientMessageId": "6751c24a-b4eb-49b8-a2cb-e2427e57e61b",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "sequenceNo": 0,
  • "editedAt": "2019-08-24T14:15:22Z",
  • "recalled": false,
  • "reactions": [
    ],
  • "status": "sent",
  • "attachments": [
    ],
  • "replyPreview": {
    },
  • "type": "USER",
  • "senderBubbleTheme": "rat"
}

Recall (soft-delete) a message (sender only, within 5 minutes)

Soft-deletes the message for all participants. The row remains in the timeline with recalled=true and an empty body so clients can render a placeholder.

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
messageId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Add reaction to message

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
messageId
required
string <uuid>
Request Body schema: application/json
required
emoji
required
string <= 64 characters

Responses

Request samples

Content type
application/json
{
  • "emoji": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "emoji": "string",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Remove reaction from message

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
messageId
required
string <uuid>
reactionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

List pinned messages for conversation

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Unpin all messages in conversation

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Pin a message in conversation

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
messageId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "conversationId": "ee6e55e8-45fe-4a3e-9bc8-4669f9fdf77a",
  • "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85",
  • "senderId": "6b2f63ba-164c-48c9-87b1-690cee2b3da3",
  • "senderDisplayName": "string",
  • "previewText": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "pinnedAt": "2019-08-24T14:15:22Z",
  • "pinnedBy": "51699c6f-7ea1-4ed9-8927-11448e2e6c19"
}

Unpin a message in conversation

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
messageId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Mark conversation read up to a given message

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
Request Body schema: application/json
required
upToMessageId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "upToMessageId": "c2de52f7-b6ea-43ee-8d36-5df53357ff03"
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Mark messages delivered up to a message that reached this device

Used when the recipient app has the message (including from a push) but the messaging websocket is not connected. Idempotent. Advances the caller's delivery cursor and notifies the sender.

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
Request Body schema: application/json
required
messageId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85"
}

Response samples

Content type
application/json
{ }

Update notification and sound preferences for the current user in a conversation

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
Request Body schema: application/json
required
notificationsEnabled
required
boolean
notificationSound
required
string
Enum: "default" "note" "chime" "pop" "silent"
mutedUntil
string or null <date-time>

Mute until this instant (UTC). Omit or null with notificationsEnabled=false to mute indefinitely. Ignored when notificationsEnabled=true.

Responses

Request samples

Content type
application/json
{
  • "notificationsEnabled": true,
  • "notificationSound": "default",
  • "mutedUntil": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "DIRECT",
  • "unreadCount": 0,
  • "peer": {
    },
  • "groupName": "string",
  • "groupAvatarUrl": "string",
  • "memberCount": 0,
  • "lastMessage": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "notificationsEnabled": true,
  • "notificationSound": "default",
  • "mutedUntil": "2019-08-24T14:15:22Z",
  • "leftAt": "2019-08-24T14:15:22Z",
  • "closeFriend": false,
  • "wallpaper": "string"
}

Set or clear the shared chat wallpaper for a conversation

Authorizations:
bearerAuth
path Parameters
conversationId
required
string <uuid>
Request Body schema: application/json
required
wallpaper
string or null <= 2048 characters

Preset id or https image URL. Null or blank clears the wallpaper back to the default background.

Responses

Request samples

Content type
application/json
{
  • "wallpaper": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "DIRECT",
  • "unreadCount": 0,
  • "peer": {
    },
  • "groupName": "string",
  • "groupAvatarUrl": "string",
  • "memberCount": 0,
  • "lastMessage": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "notificationsEnabled": true,
  • "notificationSound": "default",
  • "mutedUntil": "2019-08-24T14:15:22Z",
  • "leftAt": "2019-08-24T14:15:22Z",
  • "closeFriend": false,
  • "wallpaper": "string"
}

Current user's chat bubble theme

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "bubbleTheme": "rat"
}

Set or clear the current user's chat bubble theme

Authorizations:
bearerAuth
Request Body schema: application/json
required
bubbleTheme
string or null
Enum: "rat" "ox" "tiger" "rabbit" "dragon" "snake" "horse" "goat" "monkey" "rooster" "dog" "pig" "capybara" "shiba" "cat" "alien"

Zodiac bubble id. Null or omitted clears the theme.

Responses

Request samples

Content type
application/json
{
  • "bubbleTheme": "rat"
}

Response samples

Content type
application/json
{
  • "bubbleTheme": "rat"
}

Search messages for the authenticated user, optionally in one conversation

Authorizations:
bearerAuth
query Parameters
q
required
string [ 2 .. 100 ] characters

Message body search query (minimum 2 characters)

page
integer >= 0
Default: 0
limit
integer [ 1 .. 50 ]
Default: 20
conversationId
string <uuid>

When set, only search messages in this conversation

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a group conversation

Authorizations:
bearerAuth
Request Body schema: application/json
required
groupId
string or null <uuid>

Optional social group id to keep messaging and social groups aligned.

name
required
string <= 100 characters
avatarUrl
string or null <= 500 characters
memberUserIds
required
Array of strings <uuid> non-empty [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "name": "string",
  • "avatarUrl": "string",
  • "memberUserIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "DIRECT",
  • "unreadCount": 0,
  • "peer": {
    },
  • "groupName": "string",
  • "groupAvatarUrl": "string",
  • "memberCount": 0,
  • "lastMessage": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "notificationsEnabled": true,
  • "notificationSound": "default",
  • "mutedUntil": "2019-08-24T14:15:22Z",
  • "leftAt": "2019-08-24T14:15:22Z",
  • "closeFriend": false,
  • "wallpaper": "string"
}

List members of a group conversation

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a member to a group conversation

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
Request Body schema: application/json
required
memberUserId
required
string <uuid>
shareChatHistory
boolean
Default: true

When true (default), the new member can read existing group messages. When false, they only see messages sent after they join.

Responses

Request samples

Content type
application/json
{
  • "memberUserId": "691033db-7716-4808-9ff9-a10a4f88c52c",
  • "shareChatHistory": true
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Remove a member from a group conversation

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
memberUserId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Leave a group conversation

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Rename a group conversation

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
Request Body schema: application/json
required
name
required
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "DIRECT",
  • "unreadCount": 0,
  • "peer": {
    },
  • "groupName": "string",
  • "groupAvatarUrl": "string",
  • "memberCount": 0,
  • "lastMessage": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "notificationsEnabled": true,
  • "notificationSound": "default",
  • "mutedUntil": "2019-08-24T14:15:22Z",
  • "leftAt": "2019-08-24T14:15:22Z",
  • "closeFriend": false,
  • "wallpaper": "string"
}

Update a group conversation avatar (any member)

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
Request Body schema: application/json
required
avatarUrl
required
string <= 2048 characters

Responses

Request samples

Content type
application/json
{
  • "avatarUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "DIRECT",
  • "unreadCount": 0,
  • "peer": {
    },
  • "groupName": "string",
  • "groupAvatarUrl": "string",
  • "memberCount": 0,
  • "lastMessage": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "notificationsEnabled": true,
  • "notificationSound": "default",
  • "mutedUntil": "2019-08-24T14:15:22Z",
  • "leftAt": "2019-08-24T14:15:22Z",
  • "closeFriend": false,
  • "wallpaper": "string"
}

Transfer group admin role

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
Request Body schema: application/json
required
newAdminUserId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "newAdminUserId": "207e0b94-1bd8-4440-a934-1aad1963024a"
}

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Get total unread message count (for tab badge)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "unreadCount": 0
}

Issue a short-lived WebSocket connection ticket

Returns a one-time ticket for upgrading to GET /v1/messaging/ws?ticket={ticket}. Prefer tickets over putting the access JWT in the WebSocket query string.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "ticket": "string"
}

Bulk lookup user online presence

Returns online state and last-seen timestamps for up to 100 user IDs.

Authorizations:
bearerAuth
Request Body schema: application/json
required
userIds
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "userIds": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Stickers

Hybrid GIF and custom group stickers

List custom group stickers

Returns GIF/sticker assets uploaded for a group (stored on R2). Optional keyword filters by name or tag.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>
query Parameters
keyword
string <= 100 characters

Responses

Response samples

Content type
application/json
[]

List favorite stickers for current user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Save or update a favorite sticker

Authorizations:
bearerAuth
Request Body schema: application/json
required
provider
required
string
Enum: "klipy" "custom"
externalId
required
string <= 128 characters
url
required
string <uri> <= 2048 characters
previewUrl
string or null <uri> <= 2048 characters
name
string or null <= 255 characters
width
integer or null
height
integer or null

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "provider": "klipy",
  • "externalId": "string",
  • "url": "http://example.com",
  • "previewUrl": "http://example.com",
  • "name": "string",
  • "width": 0,
  • "height": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Remove a favorite sticker

Authorizations:
bearerAuth
path Parameters
favoriteId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

List favorite stickers for current user (feed gateway alias)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Save or update a favorite sticker (feed gateway alias)

Authorizations:
bearerAuth
Request Body schema: application/json
required
provider
required
string
Enum: "klipy" "custom"
externalId
required
string <= 128 characters
url
required
string <uri> <= 2048 characters
previewUrl
string or null <uri> <= 2048 characters
name
string or null <= 255 characters
width
integer or null
height
integer or null

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "provider": "klipy",
  • "externalId": "string",
  • "url": "http://example.com",
  • "previewUrl": "http://example.com",
  • "name": "string",
  • "width": 0,
  • "height": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Remove a favorite sticker (feed gateway alias)

Authorizations:
bearerAuth
path Parameters
favoriteId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Communication Internal

Internal-only communication-service email delivery and tracking

Send email immediately

Internal communication-service endpoint for single email delivery using raw content or a template.

Request Body schema: application/json
required
userId
string or null <uuid>
to
required
string <email>
subject
required
string
textBody
string or null
htmlBody
string or null
from
string or null <email>
fromName
string or null
cc
Array of strings <email> [ items <email > ]
bcc
Array of strings <email> [ items <email > ]
replyTo
string or null <email>
templateId
string or null
object
locale
string or null
Array of objects (AttachmentRequest)

Responses

Request samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "to": "user@example.com",
  • "subject": "string",
  • "textBody": "string",
  • "htmlBody": "string",
  • "from": "user@example.com",
  • "fromName": "string",
  • "cc": [
    ],
  • "bcc": [
    ],
  • "replyTo": "user@example.com",
  • "templateId": "string",
  • "templateVariables": {
    },
  • "locale": "string",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "messageId": "string",
  • "acceptedAt": "2019-08-24T14:15:22Z"
}

Send email asynchronously

Internal endpoint that queues email dispatch on the service async executor and returns immediately.

Request Body schema: application/json
required
userId
string or null <uuid>
to
required
string <email>
subject
required
string
textBody
string or null
htmlBody
string or null
from
string or null <email>
fromName
string or null
cc
Array of strings <email> [ items <email > ]
bcc
Array of strings <email> [ items <email > ]
replyTo
string or null <email>
templateId
string or null
object
locale
string or null
Array of objects (AttachmentRequest)

Responses

Request samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "to": "user@example.com",
  • "subject": "string",
  • "textBody": "string",
  • "htmlBody": "string",
  • "from": "user@example.com",
  • "fromName": "string",
  • "cc": [
    ],
  • "bcc": [
    ],
  • "replyTo": "user@example.com",
  • "templateId": "string",
  • "templateVariables": {
    },
  • "locale": "string",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "messageId": "string",
  • "acceptedAt": "2019-08-24T14:15:22Z"
}

Send bulk emails

Internal endpoint for up to 100 recipients per request. Returns a job id for later delivery-status queries.

Request Body schema: application/json
required
required
Array of objects (BulkRecipient) [ 1 .. 100 ] items
subject
required
string
textBody
string or null
htmlBody
string or null
from
string or null <email>
fromName
string or null
cc
Array of strings <email> [ items <email > ]
bcc
Array of strings <email> [ items <email > ]
replyTo
string or null <email>
templateId
string or null
object
locale
string or null
Array of objects (AttachmentRequest)

Responses

Request samples

Content type
application/json
{
  • "recipients": [
    ],
  • "subject": "string",
  • "textBody": "string",
  • "htmlBody": "string",
  • "from": "user@example.com",
  • "fromName": "string",
  • "cc": [
    ],
  • "bcc": [
    ],
  • "replyTo": "user@example.com",
  • "templateId": "string",
  • "templateVariables": {
    },
  • "locale": "string",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
  • "totalCount": 0,
  • "submittedAt": "2019-08-24T14:15:22Z"
}

List email delivery logs

Email-specific delivery history with optional filters for bulk jobs and recipient.

query Parameters
jobId
string <uuid>
recipient
string
status
string (EmailDeliveryStatus)
Enum: "PENDING" "SENT" "DELIVERED" "FAILED" "BOUNCED" "COMPLAINED"
page
integer
Default: 0
size
integer
Default: 20

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

Get email delivery detail

path Parameters
messageId
required
string

Responses

Response samples

Content type
application/json
{
  • "messageId": "string",
  • "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "recipient": "string",
  • "channel": "EMAIL",
  • "subject": "string",
  • "templateId": "string",
  • "status": "PENDING",
  • "provider": "string",
  • "providerMsgId": "string",
  • "errorMessage": "string",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "deliveredAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Get bulk email job stats

path Parameters
jobId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
  • "total": 0,
  • "sent": 0,
  • "failed": 0,
  • "pending": 0,
  • "delivered": 0
}

List cross-channel delivery logs

Unified delivery history across EMAIL, SMS, and PUSH channels.

Authorizations:
bearerAuth
query Parameters
userId
string <uuid>
channel
string (DeliveryChannel)
Enum: "EMAIL" "SMS" "PUSH"
status
string (EmailDeliveryStatus)
Enum: "PENDING" "SENT" "DELIVERED" "FAILED" "BOUNCED" "COMPLAINED"
recipient
string
templateId
string
from
string <date-time>
to
string <date-time>
page
integer
Default: 0
size
integer
Default: 20

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

Email provider usage snapshot

Admin view of current daily/monthly email quota counters from Postgres (email_provider_quota_usage). Returns app-wide totals plus per-provider used/limit/remaining for the smart-routing provider pool.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "routingMode": "smart",
  • "dailyPeriodKey": "20261005",
  • "monthlyPeriodKey": "202610",
  • "total": {
    },
  • "providers": [
    ]
}

Get cross-channel delivery detail

path Parameters
messageId
required
string

Responses

Response samples

Content type
application/json
{
  • "messageId": "string",
  • "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "recipient": "string",
  • "channel": "EMAIL",
  • "subject": "string",
  • "templateId": "string",
  • "status": "PENDING",
  • "provider": "string",
  • "providerMsgId": "string",
  • "errorMessage": "string",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "deliveredAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Receive Resend delivery webhooks

Resend delivery callback endpoint. Signature verification uses the Svix headers and the configured webhook secret.

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Receive Brevo delivery webhooks

Requires Authorization: Bearer <COMMUNICATION_BREVO_WEBHOOK_SECRET>. Maps sent/delivered/bounce/spam events to delivery log status.

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Receive Mailjet delivery webhooks

Requires HTTP Basic auth (COMMUNICATION_MAILJET_WEBHOOK_USER / COMMUNICATION_MAILJET_WEBHOOK_SECRET). Mailjet sent maps to DELIVERED.

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Receive Mailtrap delivery webhooks

Verifies HMAC-SHA256 Mailtrap-Signature with COMMUNICATION_MAILTRAP_WEBHOOK_SIGNING_SECRET.

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Receive SendPulse delivery webhooks

Requires query token or header X-Webhook-Token matching COMMUNICATION_SENDPULSE_WEBHOOK_SECRET.

query Parameters
token
string
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Auth Internal

Get user preferred locale and avatar

Service-to-service lookup of a user's preferred locale (vi|en) and avatar URL. Used by notification-service for localized push copy and actor avatar backfill. Requires header X-Internal-Api-Key.

Authorizations:
internalApiKey
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "preferredLocale": "vi",
  • "avatarUrl": "string"
}

Get user payment profile (internal)

Service-to-service lookup of a user's payment profile. Used by social-service for friend-only reads. Requires header X-Internal-Api-Key.

Authorizations:
internalApiKey
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "qrImageUrl": "string",
  • "accountName": "string",
  • "accountNumber": "string",
  • "bankName": "string",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List trial registrations (ops)

Ops-only listing of product trial waitlist rows. Not exposed via Kong; call auth-service directly on the internal network. Requires header X-Internal-Api-Key.

Authorizations:
internalApiKey
query Parameters
status
string
Enum: "PENDING" "WHITELISTED" "APPROVED" "REJECTED"

Omit to return every status.

platform
string
Enum: "ios" "android"

Omit to return every platform.

email
string

Case-insensitive substring match on the registrant email.

from
string <date>

Inclusive start of createdAt, as a calendar date in Asia/Ho_Chi_Minh.

to
string <date>

Inclusive end of createdAt, as a calendar date in Asia/Ho_Chi_Minh.

page
integer >= 0
Default: 0
limit
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "limit": 0,
  • "total": 0,
  • "hasMore": true
}

Export trial registrations CSV and mark Android PENDING as WHITELISTED (ops)

Exports Android emails in Google Play Console tester-list format (one email per line, no header, UTF-8 without BOM). Android PENDING rows are marked WHITELISTED in the same transaction. iOS rows are omitted. Cap 5000 rows. Not exposed via Kong. Requires header X-Internal-Api-Key.

Authorizations:
internalApiKey
query Parameters
status
string
Enum: "PENDING" "WHITELISTED" "APPROVED" "REJECTED"
platform
string
Enum: "ios" "android"
email
string
from
string <date>
to
string <date>

Responses

Response samples

Content type
application/json
{ }

Approve trial registration (ops)

Approves a trial registration and enqueues an approval email. iOS may be approved from PENDING; Android requires WHITELISTED first. Idempotent when already APPROVED (200, no second email). Not exposed via Kong. Requires header X-Internal-Api-Key.

Authorizations:
internalApiKey
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "platform": "ios",
  • "status": "PENDING",
  • "locale": "en",
  • "approvedAt": "2019-08-24T14:15:22Z",
  • "rejectedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Reject trial registration (ops)

Marks a PENDING or WHITELISTED trial registration as REJECTED. No rejection email is sent. Idempotent when already REJECTED. Not exposed via Kong. Requires header X-Internal-Api-Key.

Authorizations:
internalApiKey
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "platform": "ios",
  • "status": "PENDING",
  • "locale": "en",
  • "approvedAt": "2019-08-24T14:15:22Z",
  • "rejectedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Social Emojis

List all custom emojis

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete a custom emoji (owner only)

Authorizations:
bearerAuth
path Parameters
emojiId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

List my custom emojis

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a custom emoji

Authorizations:
bearerAuth
Request Body schema: application/json
required
alias
string or null <= 30 characters

Optional shortcode alias (lowercase letters, digits, underscore). Auto-generated if blank.

mediaId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "alias": "string",
  • "mediaId": "5a8ffac5-2288-485d-b463-90c3cd9941ad"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "4d206909-730f-409a-88f6-dcfaa8fc28cc",
  • "shortcode": "string",
  • "mediaUrl": "http://example.com",
  • "createdAt": "2019-08-24T14:15:22Z"
}

App

Batch startup payload for cold launch

Aggregates badge counts, feed first page, streak summary, conversations, and custom emojis in one request.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "badgeCounts": {
    },
  • "currentStreak": 0,
  • "hasTodayPhoto": true,
  • "feedFirstPage": [
    ],
  • "conversations": [
    ],
  • "customEmojis": [
    ]
}

Latest published Android release

Public version check for the Android client. Show an update only when latestVersionCode is greater than the installed versionCode. latestVersionName is display text and is not compared. No authentication.

Responses

Response samples

Content type
application/json
{
  • "latestVersionCode": 0,
  • "latestVersionName": "1.0.6",
  • "storeUrl": "http://example.com",
  • "forceUpdate": true
}

Latest published iOS release

Public version check for the iOS client. Show an update only when latestVersionCode is greater than CFBundleVersion. latestVersionName is display text and is not compared. channel=app-store reads the highest ios row. channel=testflight reads the highest ios-testflight row. No authentication.

query Parameters
channel
string
Default: "app-store"
Enum: "app-store" "testflight"

Responses

Response samples

Content type
application/json
{
  • "latestVersionCode": 0,
  • "latestVersionName": "1.0.6",
  • "storeUrl": "http://example.com",
  • "forceUpdate": true
}

Admin Ops

Retrieve PostgreSQL WAL-G backup status, Cloudflare R2 backup list, retention and WAL archiver telemetry

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{ }

Retrieve PostgreSQL database tables, schemas, row counts and sizes

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{ }

Retrieve transactional outbox relay backlog, lag seconds, and dead-letters

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{ }

Live health checks for microservices, database connection pool, and Redis

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{ }

Re-drive dead-letter events from outbox back to relay queue

Authorizations:
bearerAuth
Request Body schema: application/json
required
schema
required
string
ids
Array of integers

Responses

Request samples

Content type
application/json
{
  • "schema": "string",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve administrator audit trail logs with filtering

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0
limit
integer
Default: 20
action
string
adminUser
string
from
string <date-time>
to
string <date-time>
search
string

Responses

Response samples

Content type
application/json
{ }

Live real-time WebSocket messaging monitor and session stats

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{ }

List blocked IPs and devices with rate limit violations

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0
limit
integer
Default: 20
entityType
string
search
string

Responses

Response samples

Content type
application/json
{ }

Block an IP or Device

Authorizations:
bearerAuth
Request Body schema: application/json
required
entityType
required
string
Enum: "IP" "DEVICE"
entityValue
required
string
reason
required
string
durationMinutes
integer

Responses

Request samples

Content type
application/json
{
  • "entityType": "IP",
  • "entityValue": "string",
  • "reason": "string",
  • "durationMinutes": 0
}

Response samples

Content type
application/json
{ }

Unblock an IP or Device

Authorizations:
bearerAuth
path Parameters
id
required
integer

Responses

Admin Media

Get Cloudflare R2 and Media reconciliation dashboard statistics

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{ }

Music

Issue a short-lived Apple Music developer token

Signs an ES256 developer token for MusicKit clients. The MusicKit private key stays on the server. Requires an authenticated Splick user. Returns 503 when MusicKit credentials are not configured and 429 when the caller exceeds the token rate limit. Does not return a music user token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Search track metadata across providers

Aggregates metadata from Apple Music, Audius, Deezer, and iTunes. Returns an empty list with provider outcomes when every provider fails. Does not return signed audio URLs.

Authorizations:
bearerAuth
query Parameters
q
required
string [ 1 .. 100 ] characters
market
string^[A-Za-z]{2}$
limit
integer [ 1 .. 100 ]
Default: 100
pageToken
string

Responses

Response samples

Content type
application/json
{
  • "tracks": [
    ],
  • "nextPageToken": "string",
  • "outcomes": [
    ]
}

Tracks used most often in Splick

Ranks tracks by how many posts and notes currently attach them. Metadata comes from those attachments. Does not return signed audio URLs.

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 100
pageToken
string

Responses

Response samples

Content type
application/json
{
  • "tracks": [
    ],
  • "nextPageToken": "string",
  • "outcomes": [
    ]
}

List tracks saved by the current user

Returns one page of saved tracks, newest first. Pass pageToken to load the next page.

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 100
pageToken
string

Responses

Response samples

Content type
application/json
{
  • "tracks": [
    ],
  • "nextPageToken": "string"
}

Save a track for the current user

Authorizations:
bearerAuth
Request Body schema: application/json
required
provider
required
string
externalId
required
string
title
required
string
artist
string
artworkUrl
string or null

Responses

Request samples

Content type
application/json
{
  • "provider": "string",
  • "externalId": "string",
  • "title": "string",
  • "artist": "string",
  • "artworkUrl": "string"
}

Response samples

Content type
application/json
{
  • "provider": "string",
  • "externalId": "string",
  • "title": "string",
  • "artist": "string",
  • "artworkUrl": "string",
  • "saved": true
}

Remove a saved track

Authorizations:
bearerAuth
query Parameters
provider
required
string
externalId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "traceId": "string"
}

Get an ingested catalog track

Returns 404 until the background ingest job has committed the track.

Authorizations:
bearerAuth
path Parameters
trackId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "catalogTrackId": "b91c8262-53cb-4eb8-918b-dd6aeecbdbb4",
  • "title": "string",
  • "artists": [
    ],
  • "albumTitle": "string",
  • "durationMillis": 0,
  • "isrc": "string",
  • "artwork": {
    },
  • "references": [
    ],
  • "capabilities": [
    ],
  • "provenance": "string",
  • "saved": true
}

Resolve a playable resource for a catalog track

Authorizations:
bearerAuth
path Parameters
trackId
required
string <uuid>
Request Body schema: application/json
required
provider
string
externalId
string
resourceType
required
string
Enum: "PREVIEW" "STREAM" "EXTERNAL_LINK"
preferredProvider
string

Responses

Request samples

Content type
application/json
{
  • "provider": "string",
  • "externalId": "string",
  • "resourceType": "PREVIEW",
  • "preferredProvider": "string"
}

Response samples

Content type
application/json
{
  • "availability": "string",
  • "provider": "string",
  • "externalId": "string",
  • "resourceType": "string",
  • "url": "string",
  • "mimeType": "string",
  • "durationMillis": 0,
  • "expiryState": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "resolvedAt": "2019-08-24T14:15:22Z",
  • "usage": "string",
  • "license": "string",
  • "refreshSupported": true
}

Resolve a playable resource before catalog ingest

Uses provider and externalId. Does not require a catalog row.

Authorizations:
bearerAuth
Request Body schema: application/json
required
provider
string
externalId
string
resourceType
required
string
Enum: "PREVIEW" "STREAM" "EXTERNAL_LINK"
preferredProvider
string

Responses

Request samples

Content type
application/json
{
  • "provider": "string",
  • "externalId": "string",
  • "resourceType": "PREVIEW",
  • "preferredProvider": "string"
}

Response samples

Content type
application/json
{
  • "availability": "string",
  • "provider": "string",
  • "externalId": "string",
  • "resourceType": "string",
  • "url": "string",
  • "mimeType": "string",
  • "durationMillis": 0,
  • "expiryState": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "resolvedAt": "2019-08-24T14:15:22Z",
  • "usage": "string",
  • "license": "string",
  • "refreshSupported": true
}