Overview

A short link maps a generated 12-character id to a destination URL and records every click. Creating one needs a token; following one does not.

curl -X POST https://api.console.buildbase.app/api/links \
  -H "Authorization: $BUILDBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Launch announcement","url":"https://example.com/launch"}'

The response carries a linkId - that is the public handle:

{
  "_id": "665f…",
  "name": "Launch announcement",
  "url": "https://example.com/launch",
  "linkId": "a7Kd92LmQz01",
  "archived": false
}

Following a link

Two public redirect routes, neither requiring authentication:

The short form finds the organization through an index kept when the link is created, so both are fast. The org-scoped route skips that step, so prefer it when you already know the org.

What a click records

Each redirect writes an analytics row before forwarding:

Because IP and geographic data are stored per click, short links carry personal data. Include them in whatever retention policy covers the rest of your analytics.

Reading analytics

Filter by link with the standard filter parameter:

curl -G https://api.console.buildbase.app/api/links-analytics \
  -H "Authorization: $BUILDBASE_TOKEN" \
  --data-urlencode 'filter={"linkId":"a7Kd92LmQz01"}' \
  --data-urlencode 'sort={"createdAt":-1}'

Managing links

Updating url changes where an already-published link points, which is the main reason to use one.

Archiving keeps the record and its click history, but the link stops redirecting: its short URL answers 404 until you unarchive it, and then it works again as before. Use it as the switch for a link you may want back. Deleting removes the link for good, and existing shares stop resolving the same way.

Link safety

A short link sends people to a URL on our domain, so a phishing destination behind one borrows BuildBase's reputation and yours. Destinations are checked twice: when you save them and when someone clicks. The same checks cover tracked links in email and push notification clicks.

When you save a link

The destination has to be an http:// or https:// URL with no username or password in it. https://[email protected]/ reads as PayPal and goes to evil.test, so that shape is refused with Remove the username and password from the URL.

If the server has a reputation provider configured (Google Web Risk), the URL is also looked up before it is stored:

An outage at the provider never stops you saving a link. The same save-time check runs on push notification click targets, webhook endpoints and deploy hooks.

When someone clicks

Each redirect runs these in order:

1. Kill switches. If the destination is on the blocked list, the visitor gets a 403 page reading "This link has been blocked". The page never shows the destination, so nobody is invited to copy it into the address bar. For a tracked email link, the message itself can be blocked too, which disables every link in it.
2. Trusted destinations redirect straight through. That is BuildBase's own hosts plus any domains the server operator lists.
3. Everything else gets a short "Checking this link" page that asks for a verdict and then moves on by itself. A clean result continues to the destination. A flagged one shows "This link may be unsafe" and does not continue. If the provider cannot answer, the visitor sees the URL and a Continue button, because an outage is not evidence against anyone's link.

With no reputation provider configured, step 3 is skipped and links redirect as they always have. The kill switches in step 1 still apply.

In tracked email, mailto:, tel: and sms: links go straight through, and javascript:, data: and file: links are refused with the blocked page.

Automatic blocks

When a click-time check comes back malicious, the destination is blocked for your whole organization, not just for the one person who clicked. Every short link and tracked link pointing at it stops resolving, including links in emails already delivered: the email cannot be recalled, but the redirect can be refused. If the click came from a tracked email, that message is blocked as well.

Lower-confidence signals never trigger a block; they only warn the reader. No account is suspended automatically either. BuildBase staff get an alert naming the sending address and campaign, and decide what happens next.

Self-hosting? The reputation check is optional and off until you set GOOGLE_WEB_RISK_API_KEY. URL_SAFETY_TRUSTED_DOMAINS adds domains that skip the check, and URL_SAFETY_LOG_ONLY=true records verdicts without acting on them, which is a way to measure false positives before you enforce.

Next Steps

• Admin API - tokens and list-query parameters.
• Reporting - where per-module analytics live.