Branded short links + QR codes. Bearer-auth, team-scoped, two ability tracks: links:read / links:write for management, plus the separate links:analytics:read for the stats endpoints.
Base URL: https://formspring.io/api/v1
| Method | Path | Ability |
|---|---|---|
| GET | /links |
links:read |
| POST | /links |
links:write |
| GET | /links/search?q=... |
links:read |
| GET | /links/query?slug=... |
links:read |
| POST | /links/upsert |
links:write |
| POST | /links/imports |
links:write |
| GET | /links/imports/{import} |
links:read |
| GET | /links/{link} |
links:read |
| PATCH | /links/{link} |
links:write |
| DELETE | /links/{link} |
links:write |
| GET | /links/{link}/qr?format=svg|png |
links:read |
| GET | /links/{link}/stats/counters |
links:analytics:read |
| GET | /links/{link}/stats/views |
links:analytics:read |
| GET | /links/{link}/stats/heatmap |
links:analytics:read |
| GET | /links/{link}/stats/metrics |
links:analytics:read |
| GET | /links/{link}/stats/events |
links:analytics:read |
| GET | /links/{link}/stats/locations |
links:analytics:read |
| GET | /links/{link}/stats/outcomes |
links:analytics:read |
| POST | /links/{link}/conversions |
links:write |
| PATCH | /links/{link}/attribution |
links:write |
| GET, PUT | /links/{link}/destinations |
links:read, links:write |
| GET | /links/{link}/destination-history |
links:read |
The {link} path parameter accepts the link's ULID.
List links
GET /links?per_page=25
Returns the current team's links (excluding trashed), paginated.
Create a link
POST /links
Content-Type: application/json
{
"target_url": "https://example.com/very/long/landing/path?utm_source=...",
"slug": "spring-promo",
"title": "Spring 2026 promo",
"branded_domain_id": 4,
"utm_params": {
"utm_source": "newsletter",
"utm_campaign": "spring-2026"
}
}
target_urlrequired.slug- when omitted, the API picks an unambiguous slug from the configured alphabet (no 0/O/1/l/i).branded_domain_id- bind to a verified branded domain. Without this the link serves on the team's shortener domain (e.g.frmsp.io).utm_params- appended to the target URL on every redirect whenredirect_with_queryis enabled.
Response 201: LinkResource including the canonical short_url.
Import links from a CSV
POST /links/imports
Idempotency-Key: spring-2026-import
Content-Type: application/json
{
"csv": "target_url,slug,utm_campaign\nhttps://example.com/a,spring-a,spring\nhttps://example.com/b,,spring",
"dry_run": true
}
Creates many links in one call, in the background. The first row names the columns: target_url is required; slug, comment, expires_at, utm_template (the name of one of your UTM presets), utm_source, utm_medium, utm_campaign, utm_term and utm_content are optional. A file holds up to 500 rows and 1 MB. Send the text in csv, or upload it as a multipart file.
dry_run: truechecks every row exactly like the real run and writes nothing;would_createsays how many links a real run would make.- Every row is checked on its own: a bad row is reported with its line number and reasons and never blocks the good ones. Destinations on private or reserved addresses, internal hostnames and blocked domains are refused, custom slugs need a paid plan, and your plan's link limit holds across the file.
import_key(up to 64 letters, digits, dots, underscores, colons and hyphens) makes a repeat safe: rows already imported under it are reported asskipped. It defaults to a fingerprint of the file. AnIdempotency-Keyheader additionally replays the original answer for seven days.projectis the public id of the project to create the links in; it defaults to the workspace default project.
Response 202: the run, with status (queued, running, dry_run, completed, completed_with_errors or failed) and counts: total rows read equals created + would_create + skipped + failed once it has finished. A file with no target_url column, no rows, more than 500 rows or more than 1 MB answers 422 and queues nothing.
GET /links/imports/{import}
Returns the same object with errors (row, target_url, slug, messages) for the failed rows and created_links (row, id, slug, short_url). Runs are kept for 30 days. Through the MCP server use import_links and get_link_import.
Idempotent upsert
POST /links/upsert
Content-Type: application/json
{
"slug": "spring-promo",
"target_url": "https://example.com/new-target"
}
Useful from CI / sync scripts: returns 201 when the slug is new, 200 when it already exists and the row was updated. The slug field is required.
Search
GET /links/search?q=spring
Free-text search across slug, title, and target URL. Returns up to 50 matches.
Query by exact slug
GET /links/query?slug=spring-promo
Strict lookup. Returns the resource or 404 - useful when you have a known slug from an external system and want to confirm it exists before redirecting.
Update a link
PATCH /links/{link}
Content-Type: application/json
{
"target_url": "https://example.com/new-target",
"disabled_at": null
}
All fields optional. Set disabled_at to a timestamp to disable the redirect without deleting the link; set it to null to re-enable. Disabling is also what DELETE does as a guardrail.
QR code
GET /links/{link}/qr
GET /links/{link}/qr?format=png
Renders the link's branded QR code as SVG (default) or PNG. Caches edge-side; rotation of the QR happens when the team updates branding or rotates the link.
Delete a link
DELETE /links/{link}
Soft-deletes + sets disabled_at. The short URL stops serving immediately even if the soft-delete scope is bypassed by a cached resolver. Recoverable from the admin trash.
Analytics
The six /stats/* endpoints all require links:analytics:read (separate from links:read so you can issue read-only tokens that don't see who clicked what).
counters- totals by horizon (today, 7d, 30d, all-time).views- time-series of clicks at hourly/daily resolution.heatmap- 7 × 24 matrix for day-of-week × hour-of-day visualization.metrics- bucketed dimensions (browser, OS, device, referrer host, language, andsource, which splits QR scans from plain clicks).events- recent raw click events (capped, useful for live tail).locations- top countries / cities by click volume.
Click events are recorded asynchronously; analytics has an eventual-consistency lag of a few seconds during high-traffic periods.
Outcomes and experiments
Turn on Add the click id to the destination URL (PATCH /links/{link}/attribution with append_click_id) and visitors arrive with an opaque fs_click parameter. Report an outcome back with POST /links/{link}/conversions:
{ "source_fact_id": "order-1042", "conversion_type": "order", "click_id": "01J...", "value_minor": 4900, "currency": "USD" }
source_fact_idis unique per link. Replaying it answers200with the stored conversion instead of counting twice; a new conversion answers201.- Attribution uses the last non-direct touch inside the lookback window (default 30 days, configurable from 1 to 90 per link). Pass
click_idsto offer several touches; the most recent human click wins. Bots and link-preview fetchers are never eligible. - A conversion with no eligible click is stored as unattributed ("No eligible source could be linked to this conversion.") and is reported separately from verified conversions.
GET /links/{link}/stats/outcomesreturns raw clicks, estimated unique clicks, QR scans (qr_scans), verified and unattributed conversions (also split by how the visit started inby_source), the model and the window. A conversion whose source fact was withdrawn, such as a funnel qualification that was revoked, is left out. Values are summed per currency, never mixed.- When the destination is a Formspring funnel, you do not need to call the endpoint: the funnel keeps the
fs_clickid for the visit and reports leads, qualified leads, bookings and orders back to the link, but only for visitors who consented to analytics. Replays never count twice.
Forms and standalone booking pages report the same way. When the visit came through the short link and the visitor allowed analytics, the page captures the fs_click id with the campaign parameters and click ids on its address (utm_*, gclid, fbclid, ttclid, msclkid), stores them on the response or appointment, and reports a form_submission or booking outcome to the link. A visitor who refuses is still counted, as unattributed.
GET /links/{link}/destinations returns each destination's clicks and verified conversions plus a significance readout. It compares every destination with a baseline (the primary target when it has clicks) by clicks that led to a verified conversion, with a two-proportion chi-squared test and the threshold divided by the number of challengers. significance.state is:
| State | Meaning |
|---|---|
not_applicable |
Fewer than two destinations have clicks in the window. |
gathering |
A compared destination has fewer than min_clicks_per_destination clicks (100 by default), so no statistic is shown. |
inconclusive |
There is not enough evidence to choose a winner. |
significant |
winner names the destination the evidence supports. |
Read it once, when the traffic you planned for has arrived: checking it repeatedly and stopping at the first small p-value overstates confidence. The same readout is returned by the get_link_destinations agent tool, and set_link_destinations replaces the set.
PUT /links/{link}/destinations replaces a weighted destination experiment (up to 10 extra destinations; the link's own destination is the fallback). Visitors keep the destination they were first given, so changing weights only affects new visitors. Destinations that fail the safety check are paused and their share goes to the primary destination. GET /links/{link}/destination-history lists every destination the link has had; the short code never changes.
Errors
| Status | When |
|---|---|
| 403 | Token missing required ability |
| 404 | Link doesn't belong to the current team, or has been hard-deleted |
| 422 | Validation (e.g. slug collision when upserting against a different team's link) |
See also
- Tokens & abilities →
- MCP server → - same operations as agent tools
