blackgum labs Links

Docs and API

Getting started takes a minute. The REST API covers the same link operations as the app.

Getting started

  • Create a free account and confirm your email address.
  • Open Links, paste a URL and choose Create link.
  • Copy the short link and share it. Change its destination at any time from the link's page.

API basics

  • Base path: /api/v1/workspaces/{workspaceId}. Your workspace ID is shown on the Settings page.
  • Authentication: Authorization: Bearer bgl_… with an API key (Business plan and above).
  • Errors use RFC 9457 problem details with a stable code field, for example quota.links_exhausted or alias.taken.
  • Send an Idempotency-Key header when creating links. Retrying with the same key returns the original link and doesn't use extra allowance.
  • The full description is at /api/openapi/v1.json.

Create a link

POST /api/v1/workspaces/{workspaceId}/links
Authorization: Bearer bgl_…
Idempotency-Key: 9f1c2a7e-…
Content-Type: application/json

{ "destinationUrl": "https://example.com/spring-sale", "alias": "spring", "tags": ["email"] }

Other endpoints

  • GET /links?search=&state=&tag=&page=: list and filter links
  • GET /links/{linkId}, PATCH /links/{linkId}, DELETE /links/{linkId}
  • GET /aliases/availability?alias=: check a back-half
  • GET /usage: this month's allowance and usage