API reference

The fewly REST API lets you create and manage links programmatically. It's available on paid plans and authenticated with a workspace-scoped API key. Base URL: https://fewly.tech/api/v1

Authentication

Create a key in Settings → API keys and send it as a bearer token on every request. Keys are scoped to one workspace; keep them secret and rotate them if exposed.

Header

Authorization: Bearer fwly_xxx_yyy

Create a link

POST/api/v1/links

destination_urlstringrequired

The long URL to shorten.

codestring

Custom back-half. Omit for a random one.

titlestring

A label to recognize the link later.

expires_atISO 8601

When the link should stop working (paid plans).

passwordstring

Require a password before redirecting (paid plans).

curl -X POST https://fewly.tech/api/v1/links \
  -H "Authorization: Bearer fwly_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{"destination_url": "https://example.com", "code": "launch"}'

Returns 201 Created with the link. New links start pending while the safety scan runs, then become active.

201 Created

{
  "public_id": "b1f2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "code": "launch",
  "domain_host": "go.fewly.tech",
  "short_url": "https://go.fewly.tech/launch",
  "destination_url": "https://example.com",
  "title": "",
  "status": "pending",
  "safety_scan_status": "pending",
  "total_clicks": 0,
  "unique_clicks": 0,
  "is_favorite": false,
  "expires_at": null,
  "has_password": false,
  "rotation_enabled": false,
  "tags": [],
  "created_at": "2026-06-21T10:30:00Z",
  "warnings": []
}

List links

GET/api/v1/links

curl https://fewly.tech/api/v1/links \
  -H "Authorization: Bearer fwly_xxx_yyy"

Results are paginated, newest first.

200 OK

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "public_id": "b1f2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "code": "launch",
      "short_url": "https://go.fewly.tech/launch",
      "destination_url": "https://example.com",
      "status": "active",
      "total_clicks": 128,
      "unique_clicks": 97,
      "created_at": "2026-06-21T10:30:00Z"
    }
  ]
}

Retrieve, update & delete

Operate on a single link by its public_id.

GET/api/v1/links/{public_id}

PATCH/api/v1/links/{public_id}

DELETE/api/v1/links/{public_id}

PATCH accepts title, is_favorite, and status (active or disabled). DELETE returns 204 No Content.

Create many at once

POST/api/v1/links/bulk

Send a urls array (up to 200 per request). See the bulk shortening guide for the request and response shape.

Errors

Errors return the matching HTTP status with a JSON detail message.

400 — invalid input (bad URL, taken back-half).
401 — missing or invalid API key.
403 — your plan doesn’t include this feature.
404 — no link with that id in your workspace.
429 — rate limited; back off and retry.

400 Bad Request

{
  "detail": "This back-half is already in use on this domain."
}

Rate limits

Requests are rate-limited per API key and scale with your plan. A 429 response means you’ve hit the limit — wait a moment and retry. Spread large jobs out and prefer the bulk endpoint over many single calls.

Interactive schema

The full OpenAPI schema is at /api/schema/, with an explorer at /api/docs/.