Tài liệu API

Xem mọi thao tác REST và OAuth cùng host, phương thức xác thực, phạm vi, tham số, trường yêu cầu và mã phản hồi chính xác.

OpenAPI v2.1.0

Tổng quan API

Các thao tác /v2 công khai chấp nhận khóa API có phạm vi hoặc token truy cập OAuth 2.0. Các thao tác quản lý OAuth sử dụng yêu cầu riêng về trình duyệt, phiên hoặc thông tin xác thực ứng dụng.

Thử tài liệu tương tác

URL cơ sở:: https://api.s.id/v2
Thao tác: 38
Phạm vi: 10

Xác thực

Thông tin xác thực được giới hạn theo phạm vi. Thiếu phạm vi bắt buộc sẽ trả về 403 insufficient_scope. Chỉ yêu cầu quyền mà tích hợp của bạn cần.

Authorization: Bearer sk_live_...

Các endpoint

Danh mục endpoint

Mở rộng một thao tác để xem chính xác URL cơ sở, phương thức xác thực, dữ liệu đầu vào và các mã phản hồi có thể có.

Links

GET/linksLiệt kê liên kết

Returns a paginated list of the authenticated user's links.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:read

Tham số

pagequery · integer
limitquery · integer
searchquery · string
Filter by short code or URL

Phản hồi

200List of links

401

403

429

POST/linksTạo liên kết

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:write

Nội dung yêu cầu

long_urlstringBắt buộc
The destination (long) URL
titlestring
custom_slugstring
Custom short code; auto-generated when omitted
passwordstring
Optional password to protect the link
expired_atinteger
Optional expiry as a Unix timestamp (seconds)
domain_aliasstring
Custom domain to use instead of s.id

Phản hồi

200

401

403

422

429

POST/links/availableKiểm tra slug còn trống

Checks whether a custom slug is available before creating a link.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:read

Nội dung yêu cầu

shortstringBắt buộc
domain_aliasstring
Custom domain, if any

Phản hồi

200Slug is available

401

422Slug is taken or invalid

GET/links/{short}Lấy liên kết

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:read

Tham số

shortpath · stringBắt buộc
The short code of the link

Phản hồi

200

401

404

PUT/links/{short}Cập nhật liên kết

Updates a link. All fields are optional; omitted fields are left unchanged. - `password`: set a non-empty string to protect, empty string `""` to remove protection. - `custom_slug`: rename the short code (subject to quota). - `archive_at`: schedule auto-archive on a date (`YYYY-MM-DD`). - `domain_alias`: change the custom domain (must be owned by the user).

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:write

Tham số

shortpath · stringBắt buộc
The short code of the link

Nội dung yêu cầu

long_urlstring
New destination URL
titlestring
custom_slugstring
Rename the short code (subject to plan quota)
passwordstring
Set a password (`""` removes existing protection)
disposableboolean
Mark link as disposable (expires after first click)
adultboolean
Flag link as adult content
archive_atstring
Schedule auto-archive on this date (YYYY-MM-DD)
domain_aliasstring
Change the custom domain (must be owned by the user)

Phản hồi

200

401

403

404

422

429

DELETE/links/{short}Lưu trữ liên kết

Archives (soft-deletes) a link. The short code stops resolving. Use `POST /links/{short}/unarchive` to restore.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:archive

Tham số

shortpath · stringBắt buộc
The short code of the link

Phản hồi

200Link archived

401

404

429

POST/links/{short}/unarchiveKhôi phục liên kết đã lưu trữ

Restores a previously archived link, making its short code resolve again.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:write

Tham số

shortpath · stringBắt buộc
The short code of the archived link

Phản hồi

200Link restored

401

403

404

429

GET/links/{short}/statsDòng thời gian lượt nhấp liên kết

Returns a date-bucketed click-count timeline for the link.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:analytics

Tham số

shortpath · stringBắt buộc
startquery · string
endquery · string

Phản hồi

200Click timeline

401

403

404

429

GET/links/{short}/stats/lifetimeTổng lượt nhấp trọn đời

Returns the all-time total click count for a single link.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:analytics

Tham số

shortpath · stringBắt buộc

Phản hồi

200Lifetime click count

401

403

404

429

POST/links/bulkTạo hàng loạt liên kết

Create up to 100 short links in a single request. Requires a subscription plan with bulk shortening enabled. Each item reports individual success/failure — the overall request always returns 200 even if some items fail.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:write

Nội dung yêu cầu

linksarray<object>Bắt buộc

Phản hồi

200Bulk result — individual items may have success=false

401

402Plan upgrade required (bulk shortening not in plan)

403

User

GET/userLấy người dùng đã xác thực

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

user:read

Phản hồi

200User profile

401

429

GET/quotaLấy hạn mức tài khoản

Returns the authenticated user's current plan limits and usage counters.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

user:read

Phản hồi

200Account quota

401

429

Microsites

GET/micrositesLiệt kê microsite

Returns a paginated list of microsites owned by the authenticated user.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:read

Tham số

limitquery · integer
afterquery · string
Cursor for the next page (opaque string from previous response)

Phản hồi

200List of microsites

401

403

POST/micrositesTạo microsite

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:write

Nội dung yêu cầu

slugstringBắt buộc
URL-safe identifier (alphanumeric + hyphens/underscores)
titlestringBắt buộc
kindstringBắt buộc
Microsite category (e.g. `personal_branding`, `brand`, `other`)
themestring
Theme slug (optional, defaults to the platform default)

Phản hồi

200Microsite created

400Validation error (slug already taken, quota exceeded, etc.)

401

403

GET/microsites/{slug}Lấy microsite

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:read

Tham số

slugpath · stringBắt buộc

Phản hồi

200Microsite detail

401

403

404Microsite not found

PUT/microsites/{slug}Cập nhật microsite

Patches title, description, and/or visibility. All fields are optional.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:write

Tham số

slugpath · stringBắt buộc

Nội dung yêu cầu

titlestring
descriptionstring
hideboolean
Set `true` to hide the microsite from public (requires plan that supports visibility toggle)

Phản hồi

200Updated microsite

401

403

404Microsite not found

DELETE/microsites/{slug}Xóa microsite

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:delete

Tham số

slugpath · stringBắt buộc

Phản hồi

200Microsite deleted

401

403

404Microsite not found

POST/microsites/availableKiểm tra slug microsite còn trống

Checks whether a microsite slug is available before creating a microsite.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:read

Nội dung yêu cầu

slugstringBắt buộc

Phản hồi

200Slug availability result

401

403

429

GET/microsites/{slug}/componentsLiệt kê thành phần microsite

Returns the components belonging to a microsite, in display order.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:read

Tham số

slugpath · stringBắt buộc
The slug of the microsite

Phản hồi

200List of microsite components

401

403

404

429

POST/microsites/{slug}/componentsThêm thành phần microsite

Adds a new component to a microsite. The body is `{ kind, data, tag? }`. The shape of the `data` object depends on `kind`. Unknown fields are ignored, validation is per-kind, and invalid input returns `422`. All color fields are hex strings (e.g. `#1a56db`). **Kinds:** `PROFILE`, `LINK`, `HORIZONTAL_LINK`, `TEXT`, `IMAGE`, `MEDIA`, `DIVIDER`, `COUNTDOWN`, `MAPS`, `IMAGE_SLIDE`, `CV`, `AUTOPLAY_MUSIC`, `CONTACT`, `CALENDAR`, `SHOP_LISTING`, `SHOP_ITEM`, `SHOP_LEADERBOARD`. **Rules:** - `PROFILE`, `CV` and `AUTOPLAY_MUSIC` are unique — at most one per microsite. - `IMAGE_SLIDE` requires a plan with the Image Slide feature. - On create the password is always stored empty — set or change it via update (`PUT`). - Image fields (`image`, `imageBackground`, slide `image`) must be a local asset path, not a remote URL — they must match `[/.a-zA-Z0-9_-]+.(jpg|jpeg|png|svg|webp|gif|bmp)`; any value containing a scheme (`https://`), `//`, or `..` is rejected. **Shared field groups** (a kind that lists a group accepts all of its fields inside `data`): - **Button styling** (`LINK`, `CONTACT`, `CALENDAR`): `icon` (string, max 255), `textFont` (string, max 100), `textPosition` (string, max 100), `buttonEffect` (string, max 100), `buttonColor` (hex, max 20), `buttonBorderColor` (hex, max 20), `buttonIconBackground` (hex, max 20), `buttonShadowColor` (hex, max 20). - **Spoiler reveal** (`TEXT`, `IMAGE`, `MEDIA`, `MAPS`, `IMAGE_SLIDE`, `SHOP_LEADERBOARD`): `isSpoiler` (bool), `spoilerButtonText` (string, max 140), `spoilerButtonTextPosition` (string, max 100), `spoilerButtonIcon` (string), `spoilerButtonColor` (hex, max 20), `spoilerButtonFont` (string, max 100), `spoilerBackground` (string, max 100), `spoilerBackgroundOpacity` (string, max 100), `spoilerButtonBorderColor` (hex, max 20), `spoilerButtonIconBackground` (hex, max 20), `spoilerButtonShadowColor` (hex, max 20). - **Password protection** (`LINK`, `TEXT`, `IMAGE`, `MEDIA`, `MAPS`, `IMAGE_SLIDE`, `CONTACT`, `CV`, `SHOP_LEADERBOARD`): `passwordActive` (bool), `password` (string, max 255 — set via update only), `passwordMessage` (string, max 255).

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:write

Tham số

slugpath · stringBắt buộc
The slug of the microsite

Nội dung yêu cầu

kindstringBắt buộc
Component kind. The shape of `data` depends on this value.
dataobjectBắt buộc
Kind-specific component data. Its shape depends on `kind`. See the operation description and examples below.
tagstring
Optional grouping tag

Phản hồi

200Component created

401

403

404

422

429

PUT/microsites/{slug}/components/{componentId}Cập nhật thành phần microsite

Updates a single microsite component.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:write

Tham số

slugpath · stringBắt buộc
The slug of the microsite
componentIdpath · stringBắt buộc
The component ID

Nội dung yêu cầu

activebooleanBắt buộc
Whether the component is shown
kindstringBắt buộc
Component kind (e.g. `LINK`, `PROFILE`, `TEXT`)
dataobjectBắt buộc
Kind-specific component data

Phản hồi

200Component updated

401

403

404

422

429

DELETE/microsites/{slug}/components/{componentId}Xóa thành phần microsite

Deletes a single microsite component.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:delete

Tham số

slugpath · stringBắt buộc
The slug of the microsite
componentIdpath · stringBắt buộc
The component ID

Phản hồi

200Component deleted

401

403

404

429

POST/microsites/{slug}/components/orderSắp xếp lại thành phần microsite

Reorders a microsite's components according to the provided list of component IDs.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

microsites:write

Tham số

slugpath · stringBắt buộc
The slug of the microsite

Nội dung yêu cầu

ordersarray<string>Bắt buộc
Component IDs in the desired display order

Phản hồi

200Components reordered

401

403

404

422

429

Analytics

GET/statsPhân tích lượt nhấp cấp tài khoản

Returns a timeline of clicks plus breakdowns by top links, referers, locations, devices, and browsers for the authenticated account. Date range is gated by subscription plan.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

links:analytics

Tham số

startquery · string
Start date (YYYY-MM-DD). Defaults to 30 days ago.
endquery · string
End date (YYYY-MM-DD). Defaults to today.
additionalquery · boolean
Include referer, location, device, browser breakdowns

Phản hồi

200Account analytics

401

403

QR

GET/qrLấy cài đặt QR toàn cục

Returns the account-level (global) QR code settings applied to QR codes by default.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

qr:read

Phản hồi

200Global QR settings

401

403

429

PUT/qrTùy chỉnh cài đặt QR toàn cục

Updates the account-level (global) QR code settings. All fields are optional; omitted fields are left unchanged.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

qr:write

Nội dung yêu cầu

logostring
URL of the logo image embedded in the QR code
colorstring
Foreground color as a hex value, e.g. #1a56db

Phản hồi

200Updated global QR settings

401

403

422

429

GET/links/{short}/qrLấy cài đặt QR của liên kết

Returns the QR code settings for a single link.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

qr:read

Tham số

shortpath · stringBắt buộc
The short code of the link

Phản hồi

200Link QR settings

401

403

404

429

PUT/links/{short}/qrTùy chỉnh cài đặt QR của liên kết

Updates the QR code settings for a single link. All fields are optional; omitted fields are left unchanged.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API hoặc OAuth 2.0

Phạm vi

qr:write

Tham số

shortpath · stringBắt buộc
The short code of the link

Nội dung yêu cầu

logostring
URL of the logo image embedded in the QR code
colorstring
Foreground color as a hex value, e.g. #1a56db

Phản hồi

200Updated link QR settings

401

403

404

422

429

OAuth 2.0

GET/oauth/authorizeLấy dữ liệu màn hình đồng ý

A plain browser navigation here (no `Accept: application/json`) 302-redirects to the dash.s.id consent UI, preserving the query string. With `Accept: application/json`, returns application name, logo, and requested scopes for the consent UI to render.

URL cơ sở: https://api.s.id
Xác thực: Khóa API

Tham số

client_idquery · stringBắt buộc
redirect_uriquery · stringBắt buộc
response_typequery · stringBắt buộc
scopequery · string
statequery · string
Recommended. Opaque value for CSRF protection. Returned unchanged in the redirect.

Phản hồi

200Consent screen data

400Bad request

POST/oauth/tokenĐổi mã hoặc refresh token

URL cơ sở: https://api.s.id
Xác thực: Khóa API

Nội dung yêu cầu

grant_typestring
codestring
redirect_uristring
client_idstring
client_secretstring
refresh_tokenstring

Phản hồi

200Token response

400Invalid grant, unsupported_grant_type, or invalid_client

401Invalid client credentials

POST/oauth/revokeThu hồi token

Revokes an access or refresh token. Always returns 200 OK regardless of whether the token was valid (RFC 7009).

URL cơ sở: https://api.s.id
Xác thực: Khóa API

Nội dung yêu cầu

tokenstringBắt buộc

Phản hồi

200Token revoked

POST/oauth/introspectKiểm tra token

Reports whether a token is currently active and, if so, which scopes and client it belongs to (RFC 7662). Client-credential protected: `client_id`/`client_secret` identify the caller, not the token owner. Always returns `200` — including for an unknown, expired, or revoked token (`{"active": false}`) — to avoid leaking token validity to unauthenticated probing.

URL cơ sở: https://api.s.id
Xác thực: Khóa API

Nội dung yêu cầu

tokenstringBắt buộc
client_idstringBắt buộc
client_secretstringBắt buộc

Phản hồi

200Introspection result

400Missing token/client_id, or invalid client credentials

GET/oauth/userinfoLấy hồ sơ người dùng được ủy quyền

Returns the profile of the user who authorized the OAuth app. Requires `Authorization: Bearer <access_token>` (the OAuth access token, not an sk_live_ key).

URL cơ sở: https://api.s.id
Xác thực: OAuth 2.0

Phạm vi

user:read

Phản hồi

200User profile

401Unauthorized

GET/.well-known/oauth-authorization-serverSiêu dữ liệu máy chủ ủy quyền OAuth 2.0

RFC 8414 discovery document advertising every OAuth endpoint URL, supported scopes, and PKCE methods, so standards-compliant client libraries can configure themselves instead of hard-coding s.id's URLs.

URL cơ sở: https://api.s.id
Xác thực: Khóa API

Phản hồi

200Authorization server metadata

GET/api/user/oauth/appsLiệt kê ứng dụng được người dùng hiện tại ủy quyền

Returns all OAuth clients that have active tokens for the authenticated user. Auth: user session cookie (not API key).

URL cơ sở: https://api.s.id
Xác thực: Khóa API

Phản hồi

200List of connected apps

401Unauthorized

DELETE/api/user/oauth/apps/{clientId}Thu hồi mọi token của ứng dụng

Revokes all active tokens granted by the current user to the specified OAuth client.

URL cơ sở: https://api.s.id
Xác thực: Khóa API

Tham số

clientIdpath · stringBắt buộc

Phản hồi

200App access revoked

401Unauthorized

404App not found

Integrations

POST/integrations/make/webhook/unsubscribeHủy đăng ký webhook Make.com

Removes a previously registered Make.com scenario webhook subscription. Authenticated via DeveloperAPIAuth with no scope requirement.

URL cơ sở: https://api.s.id/v2
Xác thực: Khóa API

Phản hồi

200Unsubscribed

401Unauthorized

Tham chiếu phạm vi

links:read

Liệt kê và đọc liên kết

links:write

Tạo và cập nhật liên kết (tạo, sửa, khôi phục)

links:archive

Lưu trữ liên kết

links:analytics

Đọc thống kê lượt nhấp và tổng lượt nhấp trọn đời của từng liên kết

qr:read

Đọc cài đặt mã QR (toàn cục và theo từng liên kết)

qr:write

Tùy chỉnh cài đặt mã QR (toàn cục và theo từng liên kết)

user:read

Đọc hồ sơ người dùng đã xác thực và hạn mức tài khoản

microsites:read

Đọc microsite

microsites:write

Tạo, cập nhật và quản lý thành phần microsite

microsites:delete

Xóa microsite và các thành phần

Giới hạn tốc độ

Giới hạn mặc định là 38 yêu cầu mỗi phút cho mỗi thông tin xác thực—mỗi khóa API hoặc token truy cập OAuth. Ứng dụng OAuth còn có tổng giới hạn 500 yêu cầu mỗi phút trên tất cả token.

Phản hồi lỗi thường gặp

400: Yêu cầu sai định dạng hoặc không được hỗ trợ
401: Thiếu, không hợp lệ, đã thu hồi hoặc hết hạn thông tin xác thực
403: Thông tin xác thực không có phạm vi bắt buộc
404: Không tìm thấy tài nguyên được yêu cầu
422: Xác thực yêu cầu không thành công
429: Vượt quá giới hạn tần suất

Sẵn sàng bắt đầu xây dựng?

Tạo API key trong vài phút. Đã có gói miễn phí, không cần thẻ tín dụng.

Lấy API key của bạn