"Link in bio" landing pages. Bearer-auth, team-scoped, two ability tracks: bio:read / bio:write for management, plus the separate bio:analytics:read for the stats endpoints.
A Bio Page is a single public profile listing many blocks - it is not a form, survey, funnel, or link.
Base URL: https://formspring.io/api/v1
| Method | Path | Ability |
|---|---|---|
| GET | /bio-pages |
bio:read |
| POST | /bio-pages |
bio:write |
| GET | /bio-pages/search?q=... |
bio:read |
| GET | /bio-pages/{bioPage} |
bio:read |
| PATCH | /bio-pages/{bioPage} |
bio:write |
| DELETE | /bio-pages/{bioPage} |
bio:write |
| GET | /bio-pages/{bioPage}/stats/counters |
bio:analytics:read |
| GET | /bio-pages/{bioPage}/stats/views |
bio:analytics:read |
The {bioPage} path parameter accepts the page's ULID.
List pages
GET /bio-pages?per_page=25&search=acme
Returns the current team's Bio Pages, paginated and newest-first. The optional search filter matches the handle, display name, or headline. Each row includes a blocks_count.
Create a page
POST /bio-pages
Content-Type: application/json
{
"handle": "acme",
"display_name": "Acme Co.",
"headline": "Everything Acme, one link.",
"bio": "Product updates, support, and the latest drop.",
"theme": { "palette": "midnight", "accent": "#4f46e5", "button_style": "pill" },
"seo": { "title": "Acme", "description": "All of Acme in one place." },
"blocks": [
{ "type": "header", "label": "Start here", "sort_order": 0 },
{ "type": "link", "label": "Latest drop", "url": "https://acme.example/new", "sort_order": 1 },
{ "type": "link", "label": "Tracked promo", "link_id": "01J...", "sort_order": 2 },
{ "type": "social", "icon": "instagram", "url": "https://instagram.com/acme", "sort_order": 3 }
]
}
handle- optional. When omitted (or when the requested handle is taken or reserved), a readable handle is generated. Allowed characters: letters, numbers, hyphens, underscores; must start with a letter or number.display_name,headline,bio,avatar_path- optional profile fields.theme- the theme tokens (see the themes doc).seo- optionaltitle/descriptionoverrides for the page metadata.blocks- the ordered content rows. Each block has atypeoflink,header,text,social,embed,image, orform, pluslabel,url,link_id,icon,sort_order,is_active, and a type-specificconfigobject. Alinkblock may setlink_idto reuse an existing short link's routing and click history.
New pages are created as drafts. Response 201: BioPageResource with its blocks.
Show a page
GET /bio-pages/{bioPage}
Returns the page with its blocks ordered by sort_order.
Search
GET /bio-pages/search?q=acme
Free-text search across handle, display name, and headline. Returns up to 50 lightweight matches (id, handle, display_name, headline).
Update a page
PATCH /bio-pages/{bioPage}
Content-Type: application/json
{
"headline": "New season, same link.",
"is_published": true,
"blocks": [
{ "id": "01J...", "type": "link", "label": "Shop", "url": "https://acme.example/shop", "sort_order": 0 }
]
}
All fields optional. Set is_published to true to publish (the first publish stamps published_at) or false to unpublish. When blocks is present it replaces the page's block set - include every block you want to keep, each with its sort_order; include a block's id to update it in place, omit the id to create a new one.
Response 200: the updated BioPageResource.
Delete a page
DELETE /bio-pages/{bioPage}
Disables the handle immediately so the public page stops serving, then queues the page and its blocks for deletion. Response 200: { "deleted": true }.
Analytics
The two /stats/* endpoints require bio:analytics:read (separate from bio:read so you can issue read-only tokens that do not see traffic).
counters- views, distinct visitors, total clicks, per-block clicks, plus last-7-days and all-time view totals.views- time-series of views and visitors athour,day, orweekresolution.
Both accept from, to, and tz query parameters. Windows are clamped to your plan's analytics retention. Views and clicks are recorded asynchronously, so analytics has an eventual-consistency lag of a few seconds.
Audience
The people your pages collected through email and text signups. These calls need the bio:audience:export ability and a plan with audience export, and only ever return or send people with a current marketing consent. Unverified phone numbers and people who unsubscribed are left out.
POST /bio-pages/audience/export
GET /bio-pages/audience/export/{export}
Queues a CSV export (202, { "data": { "id", "status": "queued" } }). Poll the second call until status is ready; download_url is then a signed link that expires, and it needs no bearer token. The file contains personal data.
GET /bio-pages/audience/sync-targets
POST /bio-pages/audience/sync
sync-targets lists the connected email tools (data) and Google Sheets (sheets) you can send the audience to. sync takes exactly one of integration_id or sheet_id and queues the sync (202, { "status": "queued" }). Repeating a sync updates the same subscriber instead of adding another. A target from another workspace answers 404.
Import
POST /bio-pages/{bioPage}/import/preview (bio:read) and POST /bio-pages/{bioPage}/import (bio:write, authorized must be true) bring in a link list from a CSV or JSON export. See Import links from another tool.
Instagram comment replies
Awaiting Instagram's approval of the Formspring app; every call answers 404 until it is switched on. Details in Instagram comment replies.
| Call | Ability | Purpose |
|---|---|---|
GET /bio-pages/{bioPage}/instagram |
bio:read |
Connection, rules and the latest comments with the reason for each outcome |
POST /bio-pages/{bioPage}/instagram/rules |
bio:write |
Create a keyword rule (name, keywords, reply_text, optional match_mode, media_id, is_active) |
PATCH /bio-pages/{bioPage}/instagram/rules/{rule} |
bio:write |
Partial update |
DELETE /bio-pages/{bioPage}/instagram/rules/{rule} |
bio:write |
Switch off and queue deletion (202) |
POST /bio-pages/{bioPage}/instagram/disconnect |
bio:write |
Disconnect the account and switch its rules off |
Courses
Simple module and lesson bundles sold or given away from a page. Courses need a plan that includes Bio commerce (402 otherwise); the courses path segment is literal, so a page can never be mistaken for a course. See Courses for how members, refunds and drip lessons behave.
| Endpoint | Ability | Notes |
|---|---|---|
GET /bio-pages/courses |
bio:read |
Courses without their lessons |
POST /bio-pages/courses |
bio:write |
title, access_mode (paid or free), price (major units, such as 49.00), currency, optional summary and modules. Accepts an Idempotency-Key. A bad lesson rejects the whole request before anything is created |
GET /bio-pages/courses/{course} |
bio:read |
With modules[].lessons[]: body, video_url, embed_url, is_published, drip_days, files[] |
PATCH /bio-pages/courses/{course} |
bio:write |
Details; send modules to replace the curriculum |
PUT /bio-pages/courses/{course}/curriculum |
bio:write |
Replace the curriculum. Modules and lessons that are not sent are deleted with their files; an id from another course is treated as new |
POST /bio-pages/courses/{course}/publish |
bio:write |
422 with errors.publish until there is a published lesson (and a price of at least 1.00 for a paid course) |
POST /bio-pages/courses/{course}/unpublish |
bio:write |
Members keep access |
POST /bio-pages/courses/{course}/place |
bio:write |
Body bio_page_id; adds the sales block once per page (201) |
GET /bio-pages/courses/{course}/members |
bio:read |
Access state, the order behind a paid seat and lesson progress |
POST /bio-pages/courses/{course}/members/{enrollment}/revoke |
bio:write |
Ends access at once |
POST /bio-pages/courses/{course}/members/{enrollment}/restore |
bio:write |
422 while the order is refunded or in dispute |
POST /bio-pages/courses/{course}/members/{enrollment}/resend |
bio:write |
Emails a new access link |
DELETE /bio-pages/courses/{course} |
bio:write |
Takes the course down now and queues the delete (202). Orders are kept |
A lesson video_url must be a YouTube or Vimeo link. body is rich text as HTML and is sanitised on save. File attachments are uploaded in the dashboard.
Errors
| Status | When |
|---|---|
| 402 | Plan limit reached (creating beyond the Free-plan page limit) or the team's plan no longer includes Bio Pages |
| 403 | Token missing the required ability |
| 404 | Page does not belong to the current team |
| 422 | Validation (e.g. an invalid or already-used handle) |
See also
- Bio Pages overview →
- Tokens & abilities →
- MCP server → - the same operations as agent tools
