Skip to content
Swingback, home

API reference

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):

Terminal
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..."
Download the OpenAPI specJSON

Retrieve a workspace#

GET/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_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

Responses

Example

Request
curl "$SWINGBACK_API" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY"
Response · 200 OK
{
  "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

  • idstring

    Starts with ws_

  • ai_duplicatesboolean

    Whether the AI looks for duplicates of new posts and suggests merging them.

  • ai_moderationboolean

    Whether the AI screens what the public writes in the portal, and holds what it flags.

  • ai_taggingboolean

    Whether the AI tags new posts that have no tags.

  • ai_translationboolean

    Whether the AI translates posts and public comments into the portal's other languages. A read that names a language then gets a post's title and text, or a comment's text, in that language, beside the original.

  • brand_colorstringnullable

    The portal's accent color, a hex color such as #3b82f6, or null.

  • comment_approvalstring

    Whose 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 ofoffguestseveryone
  • digeststring

    Whether 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 ofonoff
  • localestring

    The 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 ofenfrdeesitptnl
  • logo_asset_idstringnullable

    The uploaded image used as the logo.

    Starts with asset_

  • logo_urlstring · URLnullable

    The logo's public address.

  • namestring

    1 to 80 characters

  • planstring

    The billing plan, such as free.

  • portal_domainstringnullable

    The portal's active custom domain, which is then its canonical host.

  • portal_done_daysinteger

    How many days a completed or closed post keeps its place in the portal's list first.

    From 0 to 365

  • portal_done_postsstring

    Where 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_placelasthidden
  • portal_guestsstring

    Whether people who don't sign in can write in the portal, as guests.

    One ofoffon
  • portal_identitiesstring

    Whether 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 ofshownhidden
  • portal_roadmapstring

    Whether the portal shows the roadmap. Your team sees it either way.

    One ofshownhidden
  • post_approvalstring

    Whose 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 ofoffguestseveryone
  • powered_byboolean

    Whether the portal shows "Powered by Swingback".

  • purge_afterstring · date-timenullable

    When a workspace that's being deleted will be purged for good, unless its owners restore it first.

  • slugstring

    The 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_urlstringnullable

    The 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

  • themestring

    The portal's color scheme. system follows the visitor's device.

    One ofsystemlightdark
  • time_zonestring

    An IANA time zone, such as Europe/Paris.

    At most 64 characters

  • widget_colorstringnullable

    The widget's accent color, a hex color such as #3b82f6, or null.

  • widget_originsarray of strings

    The origins that can embed the widget, such as https://app.example.com, or https://*.example.com for its subdomains. Only localhost can use http. An empty list allows any origin. The widget's page lists them in its Content-Security-Policy: frame-ancestors header.

    At most 20 items

  • widget_positionstring

    Which side of the page the widget's launcher is on.

    One ofleftright
  • widget_sectionsarray of strings

    The widget's sections. They always show in the order feedback, roadmap, changelog, whatever order you send.

    Each one offeedbackroadmapchangelog

    1 to 3 itemsNo duplicates

  • created_atstring · date-time
  • updated_atstring · date-time
  • deleted_atstring · date-timenullable

    Set while the workspace is being deleted. Only its owners, signed in to the dashboard, can see it then: API keys get 404.

Example

The workspace object
{
  "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
}

Search pages, sections and code: a setting, an event, a method.