spoo.me

spoo.me

REST API for spoo.me — free and open-source URL shortening service serving 400k+ redirects/day. Authenticate using either: API Key: Authorization: Bearer…

Developer tools#url-shorteners

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

REST API for spoo.me — free and open-source URL shortening service serving 400k+ redirects/day.

Authenticate using either:

  • API Key: Authorization: Bearer spoo_
  • JWT Token: Authorization: Bearer (obtained via /auth/login)
  • Session Cookie: access_token cookie (set automatically on login)

Endpoints 85

URL Shortening

  • POSTCreate Shortened URL/api/v1/shortenCreate a new shortened URL. Create a shortened URL with optional customization including password protection, expiration, click limits, and bot blocking.…
  • GETCheck Alias Availability/api/v1/shorten/check-alias?alias=mylinkCheck whether a proposed alias would be accepted by POST /api/v1/shorten. Reason codes on a negative result (length/format/reserved/ taken/emoji_policy) let…
  • GETAccepted Emoji Set/api/v1/emoji-setReturn the accepted emoji catalogue and its policy caps. emoji lists every single-codepoint emoji a custom alias may use (the picker's list), ordered by…

Me

  • DELETEDelete Account/api/v1/meRequest permanent account deletion (GDPR Art. 17). Re-authentication is required: accounts with a password send password; OAuth-only accounts confirm by…
  • GETGet Feature Availability/api/v1/me/featuresReturn the availability state of every gated feature for this account. States: enabled (render it), hidden (the feature doesn't exist for this account),…
  • GETGet Page Layout/api/v1/me/layouts/:pageFetch the saved dashboard layout for a page. Returns layout: null when the user has never customized this page — clients render their built-in default in that…
  • PUTSave Page Layout/api/v1/me/layouts/:pageSave the layout document for a page. The document is stored verbatim (last write wins) and echoed back. Versioning and validation are the client's…
  • DELETEReset Page Layout/api/v1/me/layouts/:pageRemove the saved layout so the page falls back to the client default. Idempotent: returns 204 whether or not an override existed. Authentication: Required.
  • GETGet Available Profile Pictures/api/v1/me/profile-picturesList the profile pictures available to this account. One entry per linked OAuth provider picture, with is_current marking the active one. Authentication:…
  • POSTSet Profile Picture/api/v1/me/profile-picturesSet the profile picture to one of the available provider pictures. picture_id must be an id returned by the GET endpoint; unknown ids yield 404.…
  • DELETERemove Profile Picture/api/v1/me/profile-picturesUnset the profile picture so the account falls back to the default. Idempotent: returns 200 whether or not a picture was set. Authentication: Required.
  • POSTUpload Profile Picture/api/v1/me/profile-pictures/uploadUpload a custom profile picture as a base64 data URI. Accepts image/png, image/jpeg and image/webp; size and content-type validation happens server-side…

Link Management

  • GETList Your URLs/api/v1/urlsList all URLs owned by the authenticated user. Returns a paginated list of shortened URLs with support for filtering, sorting, and full-text search on aliases…
  • DELETEBulk Delete URLs on a Custom Domain/api/v1/urls?domain=links.acme.comBulk-delete all URLs the caller owns on the given custom domain. Authentication: Required. API Key Scope: urls:manage or admin:all Rate Limits: 5/min, 50/day.…
  • GETGet URL by ID/api/v1/urls/:url_idFetch a single URL you own by its id. Returns the same item shape as one element of GET /urls — including derived status, so expired/disabled/blocked links…
  • DELETEDelete URL/api/v1/urls/:url_idDelete a URL permanently. This action is IRREVERSIBLE. The URL and its alias are permanently deleted, and the alias may be reclaimed by another user…
  • PATCHUpdate URL/api/v1/urls/:url_idUpdate an existing URL's properties. Partially update a shortened URL. Only provided fields are modified; omitted fields remain unchanged. Pass null to remove…
  • GETGet URL by Domain and Alias/api/v1/urls/:domain/:aliasFetch a single URL you own by its natural key: domain + alias. The address every short link is already known by — no id lookup round-trip needed. Returns the…
  • POSTBulk Delete URLs/api/v1/urls/bulk/deletePermanently delete up to 100 URLs you own, addressed by id. This action is irreversible. Deleted aliases become available for anyone to claim. Historical…
  • POSTBulk Update URL Status/api/v1/urls/bulk/statusActivate or deactivate up to 100 URLs you own in one request. Semantics match the single-item status endpoint exactly: ACTIVE enables redirects, INACTIVE…
  • POSTBulk Update URL Expiry/api/v1/urls/bulk/expirySet or clear the expiration on up to 100 URLs you own. One value for the whole batch — ISO 8601 or epoch seconds, must be in the future (a past value rejects…
  • POSTBulk Move URL Domain/api/v1/urls/bulk/domainMove up to 100 URLs you own to a different domain in one request. One target for the whole batch: a custom domain you own (it must be verified and ACTIVE — an…
  • POSTBulk Tag URLs/api/v1/urls/bulk/tagsAdd and remove tags (by tag id) on up to 100 URLs you own in one request. Per item the result is the link's current tags minus remove, plus add (kept once,…
  • POSTClaim anonymous URLs/api/v1/urls/claimClaim anonymously-created URLs into your account. Each item pairs a URL id with the one-time claim_token returned by the anonymous shorten call — the bearer…
  • PATCHUpdate URL Status/api/v1/urls/:url_id/statusUpdate only the status of a URL (ACTIVE / INACTIVE). Toggle a URL between active and inactive without modifying other properties. Authentication: Required —…

Statistics

  • GETURL Statistics/api/v1/statsGet aggregated click statistics across all URLs you own. Retrieve click analytics with flexible grouping, filtering, and time-range options. Authentication:…
  • GETLink Statistics/api/v1/stats/links/:url_idGet click statistics for a single URL you own. The same aggregated analytics as GET /stats, pre-scoped to one link — the response additionally echoes the…
  • GETExport Statistics/api/v1/export?format=csvExport click statistics across all URLs you own as a downloadable file. Generate a file export of click analytics data in the specified format. The response…
  • GETExport Link Statistics/api/v1/export/links/:url_id?format=csvExport click statistics for a single URL you own. The export twin of GET /stats/links/{url_id} — the same formats as GET /export, pre-scoped to one link. The…

API Keys

  • GETList API Keys/api/v1/keysList all API keys for the authenticated user. Returns metadata for all API keys (both active and revoked) belonging to the authenticated user. The full token…
  • POSTCreate API Key/api/v1/keysCreate a new API key for programmatic access. Generate a new API key with the specified name and scopes. The full token (prefixed with spoo_) is returned only…
  • DELETEDelete/Revoke API Key/api/v1/keys/:key_idDelete or revoke an API key. Remove an API key either permanently (hard delete) or by marking it as revoked (soft delete). Revoked keys stop working…

Authentication

  • POSTLogin/auth/loginAuthenticate with email and password. Returns JWT access token and sets secure HTTP-only cookies for both access and refresh tokens. The refresh token can be…
  • POSTRegister/auth/registerCreate a new user account with email and password. Immediately signs the user in by returning a JWT access token and setting secure HTTP-only cookies. A…
  • POSTRefresh Tokens/auth/refreshRotate the access and refresh token pair. Reads the refresh_token cookie, validates it, and issues a new access/refresh pair. Both cookies are replaced. If…
  • POSTLogout/auth/logoutLog the current user out by clearing auth cookies. Removes the access_token and refresh_token HTTP-only cookies. Always succeeds regardless of whether the…
  • POSTRestore Account/auth/restoreCancel a pending account deletion during the grace period. Two mutually exclusive proofs: email + password validates the account credentials, restore_token…
  • GETGet Current User/auth/meReturn the authenticated user's full profile. Includes email, verification status, linked OAuth providers, plan, and profile picture. Useful for populating…
  • PATCHUpdate Current User/auth/meUpdate the authenticated user's profile. Currently only user_name is editable. Registration makes the display name write-once, so accounts that skipped it…
  • POSTSet Password/auth/set-passwordSet a password for an OAuth-only account. Allows users who signed up via OAuth to add a password so they can also log in with email + password. Fails if the…
  • POSTSend Verification Email/auth/send-verificationSend a 6-digit OTP verification code to the user's email. The code expires after the duration returned in expires_in (seconds). Returns 400 if the user's…
  • POSTVerify Email/auth/verify-emailVerify the user's email address using a 6-digit OTP code. On success, new JWT tokens are issued with email_verified=true in the claims, and auth cookies are…
  • POSTRequest Password Reset/auth/request-password-resetRequest a password-reset OTP to be sent via email. Always returns the same success response regardless of whether the email is registered. This prevents user…
  • POSTReset Password/auth/reset-passwordReset the account password using a 6-digit OTP code. The OTP must have been requested via POST /auth/request-password-reset. On success the password is…
  • POSTExchange Device Auth Code/auth/device/tokenExchange a one-time device auth code for JWT tokens. The code is obtained from the callback page after the user authenticates on spoo.me. The PKCE…
  • POSTRefresh Device Auth Tokens/auth/device/refreshRefresh an app's JWT tokens using a refresh token. Accepts the refresh token in the request body (not cookies) for use by external apps (browser extensions,…
  • GETGet Onboarding State/auth/onboardingReturn the caller's onboarding resume pointer. Authentication: Required (JWT or API key) Rate Limits: 60/min Notes: The pointer self-expires 24h after the…
  • PUTUpdate Onboarding State/auth/onboardingPersist the caller's resume pointer (refreshes the 24h TTL). Authentication: Required (JWT or API key) Rate Limits: 30/min Notes: Best-effort — if Redis is…
  • POSTComplete Onboarding/auth/onboarding/completeMark onboarding finished for this account. Stamps onboarded_at on the user document (first completion wins — repeat calls are idempotent and keep the original…

OAuth

  • GETList OAuth Providers/oauth/providersList all OAuth providers linked to the authenticated user's account. Returns each linked provider's name, email, and link date, plus whether the user has a…
  • DELETEUnlink OAuth Provider/oauth/providers/:provider_name/unlinkRemove an OAuth provider link from the authenticated user's account. Fails if the provider is the user's only authentication method (i.e., no password set and…
  • GETOAuth Login/oauth/:providerInitiate the OAuth authorization flow for the given provider. Redirects the user to the provider's consent screen (e.g., Google, GitHub). After the user…
  • GETOAuth Callback/oauth/:provider/callbackHandle the OAuth provider callback after user authorization. Validates the CSRF state parameter, exchanges the authorization code for an access token, fetches…
  • GETLink OAuth Provider/oauth/:provider/linkInitiate an OAuth flow to link a provider to the authenticated account. Similar to GET /oauth/{provider} but includes the user's ID in the state token so the…

Reports & Contact

  • POSTReport URLs/api/v1/reportsReport shortened URLs for abuse — one or many per request. Accepts bare codes or full short URLs (custom domains included) and returns a per-item…
  • POSTContact/api/v1/contactSend a message to the site operators. JSON twin of the /contact form — same service, same webhook, same budget values. Authentication: None. Rate Limits:…

System

  • GETHealth Check/healthCheck the health of the application and its dependencies. Pings MongoDB and Redis to determine overall system status: healthy (200): Both MongoDB and Redis…

Tags

  • GETList Your Tags/api/v1/tagsEvery tag in your account with the number of links carrying it, oldest first. API Key Scope: urls:manage, urls:read, or admin:all Rate Limits: 60/min, 5,000/day
  • POSTCreate a Tag/api/v1/tagsCreate a tag. Names are lowercased and trimmed; a name you already have answers 409 conflict. Omit color to get the least-used palette colour in your account;…
  • DELETEDelete a Tag/api/v1/tags/:tag_idDelete the tag and remove it from every link that carried it. The links themselves are untouched otherwise. API Key Scope: urls:manage or admin:all Rate…
  • PATCHRename or Recolour a Tag/api/v1/tags/:tag_idChange the name, colour or icon. Links keep pointing at the tag by id, so a rename shows up everywhere at once. Renaming onto a name you already have answers…

Public

  • GETPublic URL Statistics/api/v1/public/stats/:short_codeGet public click statistics for a single short link. Resolves both URL generations (plus emoji aliases) on the system default domain and returns link facts…
  • POSTPublic URL Statistics (password unlock)/api/v1/public/stats/:short_codeSame as the GET variant, carrying a password in the JSON body. The body is the ONLY way a password travels to this endpoint — query-string passwords are…
  • GETPublic Link Preview/api/v1/public/preview/:short_codePreview where a short link leads before following it. Returns the link's resolved facts — status, creation date, whether a password gates it, and (only while…

Apps

  • GETList Connected Apps/api/v1/appsList the apps connected to the authenticated user's account. Returns one entry per active device-auth grant (revoked grants are excluded), newest first. app…

Custom Domains

  • GETList Custom Domains/api/v1/custom-domainsList custom domains owned by the authenticated user. Reads bypass the feature flag so owners can still see state during a rollback. Authentication: Required…
  • POSTRegister Custom Domain/api/v1/custom-domainsRegister a new custom domain for branded short links. The domain is born in PENDING state. The user must publish the DNS records returned in dns_records at…
  • POSTVerify Custom Domain/api/v1/custom-domains/:domain_id/verifyTrigger a fresh verification check for a custom domain. The verifier dispatched depends on the chosen DCV method (CF HTTP DCV on CF SaaS deployments,…
  • GETGet Custom Domain/api/v1/custom-domains/:domain_idFetch a single custom domain owned by the caller. Used by the dashboard detail view + auto-poll after Verify. Bypasses the feature flag like other read…
  • DELETERevoke Custom Domain/api/v1/custom-domains/:domain_idRevoke a custom domain. REVOKED is terminal. With ?cascade=true, all URLs owned by the caller on the domain are bulk-deleted. With ?cascade=false (default),…
  • PATCHUpdate Custom Domain Routing/api/v1/custom-domains/:domain_idUpdate the per-domain routing config. Partial update — send only the fields you want to change. Omit a field to leave it untouched. Send explicit null to…
  • DELETERemove Revoked Custom Domain/api/v1/custom-domains/:domain_id/permanentPermanently delete a revoked custom domain to free the account slot. Soft-deleted (REVOKED) domains continue to occupy the caller's per-account quota so…

Metadata

  • GETFetch Destination Meta Tags/api/v1/metadata?url=https://example.com/articleFetch a destination page and return its existing meta tags. Use this to prefill meta_tags before customizing a link's social preview, or to check how a page…
  • GETExpand a Short Link/api/v1/expand?url=https://spoo.me/exampleFollow a URL's redirect chain and return every hop in order. Works on links from any shortener. Bodies are never fetched — only each hop's status and Location…
  • GETDomain Records/api/v1/domain-intel?host=github.comDNS records, registration data, and TLS certificate of a host. Registration comes from the registry's own RDAP server; age_days is the strongest quick signal…

Webhooks

  • GETList Webhook Event Types/api/v1/webhooks/event-typesThe public webhook event catalog — documentation as API. Every subscribable event type with its category, firing frequency, and an exact sample payload (the…
  • GETList Webhook Endpoints/api/v1/webhooksList all webhook endpoints on the account (secrets never included).
  • POSTCreate Webhook Endpoint/api/v1/webhooksRegister an HTTPS endpoint to receive event deliveries. The signing_secret is returned only in this response — store it; it is what your server uses to verify…
  • GETGet Webhook Endpoint/api/v1/webhooks/:endpoint_id
  • DELETEDelete Webhook Endpoint/api/v1/webhooks/:endpoint_id
  • PATCHUpdate Webhook Endpoint/api/v1/webhooks/:endpoint_idUpdate url, events, scope, flavor, description, or pause/resume. A new url is re-checked (https + public address) before it takes effect. status accepts…
  • GETReveal Signing Secret/api/v1/webhooks/:endpoint_id/secretThe full signing secret, for the endpoint owner. Secrets are stored encrypted and readable on demand; treat the response like a password. Authentication:…
  • POSTSend Test Event/api/v1/webhooks/:endpoint_id/testSend a sample of any catalog event through the real pipeline — rendered in the endpoint's flavor, signed with its real secret — and return the delivery…
  • GETList Webhook Deliveries/api/v1/webhooks/:endpoint_id/deliveriesThe delivery log: what was sent, when, each attempt's outcome, and the exact rendered body (30-day retention).
  • POSTRetry Delivery/api/v1/webhooks/:endpoint_id/deliveries/:delivery_id/retryRedeliver a completed delivery: same webhook-id, same body, fresh attempt — consumers dedup on webhook-id.

API details

Base URL
https://spoo.me
Authentication
A bearer token in the Authorization header
A bearer token in the Authorization header
Operations
85 operations on 66 pathsGET 34POST 32DELETE 11PATCH 6PUT 2
Main resources
Authentication 17Link Management 13Webhooks 10Me 9Custom Domains 7OAuth 5Statistics 4Tags 4API Keys 3Metadata 3
Response formats
application/json application/xml application/zip
Description format
OpenAPI 3.1.0, API version 1.0.0

How to test the spoo.me in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the spoo.me collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Create Shortened URL” (POST /api/v1/shorten), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the spoo.me?

REST API for spoo.me — free and open-source URL shortening service serving 400k+ redirects/day. Authenticate using either: API Key: Authorization: Bearer… It is listed under Developer tools and has 85 endpoints.

Who publishes the spoo.me?

It is listed from spoo.me's public API description (an OpenAPI document), not published by spoo.me on Swastik Codes. Anyone who controls spoo.me can claim the profile by adding a DNS TXT record.

What is the base URL of the spoo.me?

Requests go to https://spoo.me. Endpoint paths are added to this base URL.

How do I authenticate with the spoo.me?

It accepts 2 methods: A bearer token in the Authorization header; A bearer token in the Authorization header.

How many endpoints does the spoo.me have?

85 operations on 66 paths (34 GET, 32 POST, 11 DELETE, 6 PATCH, 2 PUT). The largest groups are Authentication, Link Management, Webhooks, Me.

Is forking the spoo.me free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.