API reference

The HTTP API uses Laravel Sanctum. Authenticate with a Bearer token. Workspace routes require membership and scoped token abilities for read and write operations.

Authentication model

• Session cookies apply to browser use; programmatic access uses personal access tokens.
• Tokens are created per user and carry one or more abilities, e.g. workspace:acme-corp:read and workspace:acme-corp:write.
• Read routes require a matching :read (or :write). Mutating routes require :write.

Base URL

All paths below are relative to your deployment origin. Versioned endpoints are available under /api/v1 and should be preferred for new integrations. Legacy unversioned endpoints remain for backward compatibility during migration.

Rate limiting

Workspace API routes are throttled per authenticated user and workspace (see API_WORKSPACE_REQUESTS_PER_MINUTE in environment configuration, default 120 per rolling minute). Expect HTTP 429 when exceeded.

Endpoints

Create a token (example)

While signed in, POST JSON with a display name. The response includes the plaintext token—store it securely.

curl -X POST "https://link.iutils.net/api/workspaces/{workspace}/tokens" \
  -H "Authorization: Bearer {existing_token_or_session_not_used_here}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI export bot","scope":"read_only"}'

In practice, token creation is typically performed from the browser while authenticated; use the same route with your session or an existing token that already has workspace access.

List tokens (example)

curl -X GET "https://link.iutils.net/api/workspaces/{workspace}/tokens" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Revoke token (example)

curl -X DELETE "https://link.iutils.net/api/workspaces/{workspace}/tokens/{tokenId}" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

List links (example)

curl -X GET "https://link.iutils.net/api/workspaces/{workspace}/links" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Analytics summary (example)

Members without analytics export permission (see Team & roles) receive HTTP 403 on analytics routes.

curl -X GET "https://link.iutils.net/api/workspaces/{workspace}/analytics/summary?start_date=2026-01-01&end_date=2026-01-31" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Analytics scans (example)

curl -X GET "https://link.iutils.net/api/workspaces/{workspace}/analytics/scans?per_page=50&page=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Create webhook endpoint (example)

curl -X POST "https://link.iutils.net/api/workspaces/{workspace}/webhooks" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/scan","event_types":["scan.logged","conversion.recorded"],"enabled":true}'

Record a conversion (example)

Report server-side conversions against a link by short code or id. Each conversion also fans out to webhook endpoints subscribed to conversion.recorded.

curl -X POST "https://link.iutils.net/api/workspaces/{workspace}/conversions" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"short_code":"spring24","source":"api","meta":{"order_id":"A-1001"}}'

Analytics breakdown (example)

Ranked rows per dimension: country, city, region, device, browser, os, or referrer. Accepts the same filters as other analytics endpoints plus trigger=link|qr.

curl -X GET "https://link.iutils.net/api/workspaces/{workspace}/analytics/breakdown?dimension=country&trigger=qr" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

List webhook deliveries (example)

curl -X GET "https://link.iutils.net/api/workspaces/{workspace}/webhooks/{id}/deliveries?page=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Errors

Versioned routes return a standard error envelope: { error: { code, message, details? } }. Common codes include unauthenticated (401), forbidden (403), not_found (404), validation_failed (422), and rate-limit responses (429).

Idempotency and side effects

GET requests are read-only. POST to create a token is not idempotent—each call mints a new token. Revoke tokens via the DELETE endpoint or the workspace token settings screen.

Audit trail

Creating API tokens may be recorded in the audit log when enabled, including token name and workspace context.

Related guides

Team & roles · Security & privacy · Trust center · Troubleshooting