API Reference

Browse every REST and OAuth operation with its exact host, authentication method, scopes, parameters, request fields, and response codes.

OpenAPI v2.1.0

API overview

Public /v2 operations accept either a scoped API key or an OAuth 2.0 access token. OAuth management operations use their own browser, session, or client-credential requirements.

Try Interactive Reference

Base URL:: https://api.s.id/v2
Operations: 38
Scopes: 10

Authentication

Credentials are scoped. Missing a required scope returns 403 insufficient_scope. Request only the permissions your integration needs.

Authorization: Bearer sk_live_...

Endpoints

Endpoint catalog

Expand an operation to inspect its exact base URL, authentication, inputs, and possible response codes.

Links

GET/linksList links

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:read

Parameters

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

Responses

200List of links

401

403

429

POST/linksCreate a link

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:write

Request body

long_urlstringRequired
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

Responses

200

401

403

422

429

POST/links/availableCheck slug availability

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:read

Request body

shortstringRequired
domain_aliasstring
Custom domain, if any

Responses

200Slug is available

401

422Slug is taken or invalid

GET/links/{short}Get a link

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:read

Parameters

shortpath · stringRequired
The short code of the link

Responses

200

401

404

PUT/links/{short}Update a link

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).

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:write

Parameters

shortpath · stringRequired
The short code of the link

Request body

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)

Responses

200

401

403

404

422

429

DELETE/links/{short}Archive a link

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:archive

Parameters

shortpath · stringRequired
The short code of the link

Responses

200Link archived

401

404

429

POST/links/{short}/unarchiveRestore an archived link

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:write

Parameters

shortpath · stringRequired
The short code of the archived link

Responses

200Link restored

401

403

404

429

GET/links/{short}/statsLink click timeline

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:analytics

Parameters

shortpath · stringRequired
startquery · string
endquery · string

Responses

200Click timeline

401

403

404

429

GET/links/{short}/stats/lifetimeLifetime click count

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:analytics

Parameters

shortpath · stringRequired

Responses

200Lifetime click count

401

403

404

429

POST/links/bulkBulk create links

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.

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:write

Request body

linksarray<object>Required

Responses

200Bulk result — individual items may have success=false

401

402Plan upgrade required (bulk shortening not in plan)

403

User

GET/userGet authenticated user

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

user:read

Responses

200User profile

401

429

GET/quotaGet account quota

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

user:read

Responses

200Account quota

401

429

Microsites

GET/micrositesList microsites

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:read

Parameters

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

Responses

200List of microsites

401

403

POST/micrositesCreate a microsite

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:write

Request body

slugstringRequired
URL-safe identifier (alphanumeric + hyphens/underscores)
titlestringRequired
kindstringRequired
Microsite category (e.g. `personal_branding`, `brand`, `other`)
themestring
Theme slug (optional, defaults to the platform default)

Responses

200Microsite created

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

401

403

GET/microsites/{slug}Get a microsite

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:read

Parameters

slugpath · stringRequired

Responses

200Microsite detail

401

403

404Microsite not found

PUT/microsites/{slug}Update a microsite

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:write

Parameters

slugpath · stringRequired

Request body

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

Responses

200Updated microsite

401

403

404Microsite not found

DELETE/microsites/{slug}Delete a microsite

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:delete

Parameters

slugpath · stringRequired

Responses

200Microsite deleted

401

403

404Microsite not found

POST/microsites/availableCheck microsite slug availability

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:read

Request body

slugstringRequired

Responses

200Slug availability result

401

403

429

GET/microsites/{slug}/componentsList microsite components

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:read

Parameters

slugpath · stringRequired
The slug of the microsite

Responses

200List of microsite components

401

403

404

429

POST/microsites/{slug}/componentsAdd a microsite component

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).

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:write

Parameters

slugpath · stringRequired
The slug of the microsite

Request body

kindstringRequired
Component kind. The shape of `data` depends on this value.
dataobjectRequired
Kind-specific component data. Its shape depends on `kind`. See the operation description and examples below.
tagstring
Optional grouping tag

Responses

200Component created

401

403

404

422

429

PUT/microsites/{slug}/components/{componentId}Update a microsite component

Updates a single microsite component.

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:write

Parameters

slugpath · stringRequired
The slug of the microsite
componentIdpath · stringRequired
The component ID

Request body

activebooleanRequired
Whether the component is shown
kindstringRequired
Component kind (e.g. `LINK`, `PROFILE`, `TEXT`)
dataobjectRequired
Kind-specific component data

Responses

200Component updated

401

403

404

422

429

DELETE/microsites/{slug}/components/{componentId}Delete a microsite component

Deletes a single microsite component.

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:delete

Parameters

slugpath · stringRequired
The slug of the microsite
componentIdpath · stringRequired
The component ID

Responses

200Component deleted

401

403

404

429

POST/microsites/{slug}/components/orderReorder microsite components

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

microsites:write

Parameters

slugpath · stringRequired
The slug of the microsite

Request body

ordersarray<string>Required
Component IDs in the desired display order

Responses

200Components reordered

401

403

404

422

429

Analytics

GET/statsAccount-level click analytics

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.

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

links:analytics

Parameters

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

Responses

200Account analytics

401

403

QR

GET/qrGet global QR settings

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

qr:read

Responses

200Global QR settings

401

403

429

PUT/qrCustomize global QR settings

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

qr:write

Request body

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

Responses

200Updated global QR settings

401

403

422

429

GET/links/{short}/qrGet a link's QR settings

Returns the QR code settings for a single link.

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

qr:read

Parameters

shortpath · stringRequired
The short code of the link

Responses

200Link QR settings

401

403

404

429

PUT/links/{short}/qrCustomize a link's QR settings

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

Base URL: https://api.s.id/v2
Authentication: API key or OAuth 2.0

Scope

qr:write

Parameters

shortpath · stringRequired
The short code of the link

Request body

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

Responses

200Updated link QR settings

401

403

404

422

429

OAuth 2.0

GET/oauth/authorizeGet consent screen data

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.

Base URL: https://api.s.id
Authentication: API key

Parameters

client_idquery · stringRequired
redirect_uriquery · stringRequired
response_typequery · stringRequired
scopequery · string
statequery · string
Recommended. Opaque value for CSRF protection. Returned unchanged in the redirect.

Responses

200Consent screen data

400Bad request

POST/oauth/tokenExchange code or refresh token

Base URL: https://api.s.id
Authentication: API key

Request body

grant_typestring
codestring
redirect_uristring
client_idstring
client_secretstring
refresh_tokenstring

Responses

200Token response

400Invalid grant, unsupported_grant_type, or invalid_client

401Invalid client credentials

POST/oauth/revokeRevoke a token

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

Base URL: https://api.s.id
Authentication: API key

Request body

tokenstringRequired

Responses

200Token revoked

POST/oauth/introspectIntrospect a 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.

Base URL: https://api.s.id
Authentication: API key

Request body

tokenstringRequired
client_idstringRequired
client_secretstringRequired

Responses

200Introspection result

400Missing token/client_id, or invalid client credentials

GET/oauth/userinfoGet authorized user profile

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).

Base URL: https://api.s.id
Authentication: OAuth 2.0

Scope

user:read

Responses

200User profile

401Unauthorized

GET/.well-known/oauth-authorization-serverOAuth 2.0 Authorization Server Metadata

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.

Base URL: https://api.s.id
Authentication: API key

Responses

200Authorization server metadata

GET/api/user/oauth/appsList apps authorized by the current user

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

Base URL: https://api.s.id
Authentication: API key

Responses

200List of connected apps

401Unauthorized

DELETE/api/user/oauth/apps/{clientId}Revoke all tokens for an app

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

Base URL: https://api.s.id
Authentication: API key

Parameters

clientIdpath · stringRequired

Responses

200App access revoked

401Unauthorized

404App not found

Integrations

POST/integrations/make/webhook/unsubscribeUnsubscribe a Make.com webhook

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

Base URL: https://api.s.id/v2
Authentication: API key

Responses

200Unsubscribed

401Unauthorized

Scope Reference

links:read

List and read links

links:write

Create and update links (create, edit, restore)

links:archive

Archive links

links:analytics

Read per-link click statistics and lifetime counts

qr:read

Read QR code settings (global and per-link)

qr:write

Customize QR code settings (global and per-link)

user:read

Read the authenticated user profile and account quota

microsites:read

Read microsites

microsites:write

Create, update and manage components of microsites

microsites:delete

Delete microsites and their components

Rate Limits

The default limit is 38 requests per minute per credential—per API key or OAuth access token. OAuth apps also have a combined ceiling of 500 requests per minute across their tokens.

Common error responses

400: Malformed or unsupported request
401: Missing, invalid, revoked, or expired credential
403: Credential does not have the required scope
404: Requested resource was not found
422: Request validation failed
429: Rate limit exceeded

Ready to start building?

Create an API key in minutes. Free tier included, no credit card required.

Get your API key