Workspaces
An API key belongs to one workspace and sees only that one. The workspace's id (ws_…) is in every path: read the workspace itself to get its settings and its plan.
The examples read your API key and your workspace's base URL from two shell variables. Set them once, with your workspace's id in place of ws_... (API keys says where to find both):
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..." Retrieve a workspace#
/ v1/ workspaces/ {workspace_id}Any API key: Read or Read and write
Returns the workspace, with its settings and its plan. Once a workspace is deleted, every API key gets 404 for it: only its owners, signed in to the dashboard, can read it then, with deleted_at and purge_after set.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Responses
- 200OKThe workspace object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl "$SWINGBACK_API" \
-H "Authorization: Bearer $SWINGBACK_API_KEY"{
"id": "ws_01h455vb4pex5vsknk084sn02q",
"ai_duplicates": true,
"ai_moderation": false,
"ai_tagging": true,
"ai_translation": false,
"brand_color": null,
"comment_approval": "off",
"digest": "on",
"locale": "en",
"logo_asset_id": null,
"logo_url": null,
"name": "Acme",
"plan": "pro",
"portal_domain": null,
"portal_done_days": 0,
"portal_done_posts": "in_place",
"portal_guests": "off",
"portal_identities": "shown",
"portal_roadmap": "shown",
"post_approval": "off",
"powered_by": true,
"purge_after": null,
"slug": "acme",
"sso_login_url": null,
"theme": "system",
"time_zone": "America/New_York" ,
"widget_color": null,
"widget_origins": [
"https://app.acme.example.com"
],
"widget_position": "right",
"widget_sections": [
"feedback",
"roadmap",
"changelog"
],
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"deleted_at": null
}The workspace object#
Fields
idstringStarts with
ws_ai_duplicatesbooleanWhether the AI looks for duplicates of new posts and suggests merging them.
ai_moderationbooleanWhether the AI screens what the public writes in the portal, and holds what it flags.
ai_taggingbooleanWhether the AI tags new posts that have no tags.
ai_translationbooleanWhether the AI translates posts and public comments into the portal's other languages. A read that names a
languagethen gets a post's title and text, or a comment's text, in that language, beside the original.brand_colorstringnullableThe portal's accent color, a hex color such as
#3b82f6, or null.comment_approvalstringWhose posts (or comments) written in the portal wait for your team's approval: nobody's (
off), guests' (guests) or everyone's (everyone). Whatever this says, a text with sensitive data or many links, or one that repeats its author's recent text, is held.One ofoffguestseveryonedigeststringWhether the workspace's end users get the weekly digest, on Monday mornings in the workspace's time zone: the week's top new posts, shipped posts and changelog entries.
One ofonofflocalestringThe workspace's default language. The portal uses it for visitors whose language it doesn't offer, and emails use it for people whose language isn't known. The changelog's RSS feed, AI drafts and search use it too. The dashboard itself is in English.
One ofenfrdeesitptnllogo_asset_idstringnullableThe uploaded image used as the logo.
Starts with
asset_logo_urlstring · URLnullableThe logo's public address.
namestring1 to 80 characters
planstringThe billing plan, such as
free.portal_domainstringnullableThe portal's active custom domain, which is then its canonical host.
portal_done_daysintegerHow many days a completed or closed post keeps its place in the portal's list first.
From 0 to 365
portal_done_postsstringWhere the portal's list puts a post completed or closed for
portal_done_days: where the list's order puts it (in_place), after every other post (last), or nowhere (hidden). Only while the list has no status chosen and no search: then every post is listed as usual.One ofin_placelasthiddenportal_guestsstringWhether people who don't sign in can write in the portal, as guests.
One ofoffonportal_identitiesstringWhether the portal shows who wrote what (names and avatars), or only whether it came from a customer or your team. The portal never shows emails or ids.
One ofshownhiddenportal_roadmapstringWhether the portal shows the roadmap. Your team sees it either way.
One ofshownhiddenpost_approvalstringWhose posts (or comments) written in the portal wait for your team's approval: nobody's (
off), guests' (guests) or everyone's (everyone). Whatever this says, a text with sensitive data or many links, or one that repeats its author's recent text, is held.One ofoffguestseveryonepowered_bybooleanWhether the portal shows "Powered by Swingback".
purge_afterstring · date-timenullableWhen a workspace that's being deleted will be purged for good, unless its owners restore it first.
slugstringThe name in the workspace's portal address: lowercase letters, digits and single hyphens, starting with a letter. Some names are reserved.
3 to 40 characters
sso_login_urlstringnullableThe page on your site where the portal sends visitors to sign in. Your page signs them in and sends them back to the portal with an identity token. Null when the portal signs people in itself.
At most 2,048 characters
themestringThe portal's color scheme.
systemfollows the visitor's device.One ofsystemlightdarktime_zonestringAn IANA time zone, such as
Europe/Paris.At most 64 characters
widget_colorstringnullableThe widget's accent color, a hex color such as
#3b82f6, or null.widget_originsarray of stringsThe origins that can embed the widget, such as
https://app.example.com, orhttps://*.example.comfor its subdomains. Only localhost can use http. An empty list allows any origin. The widget's page lists them in itsContent-Security-Policy: frame-ancestorsheader.At most 20 items
widget_positionstringWhich side of the page the widget's launcher is on.
One ofleftrightwidget_sectionsarray of stringsThe widget's sections. They always show in the order
feedback,roadmap,changelog, whatever order you send.Each one offeedbackroadmapchangelog1 to 3 itemsNo duplicates
created_atstring · date-timeupdated_atstring · date-timedeleted_atstring · date-timenullableSet while the workspace is being deleted. Only its owners, signed in to the dashboard, can see it then: API keys get 404.
Example
{
"id": "ws_01h455vb4pex5vsknk084sn02q",
"ai_duplicates": true,
"ai_moderation": false,
"ai_tagging": true,
"ai_translation": false,
"brand_color": null,
"comment_approval": "off",
"digest": "on",
"locale": "en",
"logo_asset_id": null,
"logo_url": null,
"name": "Acme",
"plan": "pro",
"portal_domain": null,
"portal_done_days": 0,
"portal_done_posts": "in_place",
"portal_guests": "off",
"portal_identities": "shown",
"portal_roadmap": "shown",
"post_approval": "off",
"powered_by": true,
"purge_after": null,
"slug": "acme",
"sso_login_url": null,
"theme": "system",
"time_zone": "America/New_York" ,
"widget_color": null,
"widget_origins": [
"https://app.acme.example.com"
],
"widget_position": "right",
"widget_sections": [
"feedback",
"roadmap",
"changelog"
],
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"deleted_at": null
}