Skip to content
Swingback, home

API reference

Moderation

What end users write in the portal can wait for your team's review: it's held, with the reasons in moderation_flags, until someone approves or rejects it. The review queues are the posts and the comments with moderation_state=held. A banned end user can still read the portal, but can't write in it.

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

Approve or reject a post#

POST/v1/workspaces/{workspace_id}/posts/{post_id}/moderation

An API key with Read and write access

An approved post shows in the portal. A rejected post shows only to its author and your team. Either decision resolves the post's moderation_flags. Making the same decision again changes nothing.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • post_idstringrequired

    The post's id.

    Starts with post_

Headers

  • Idempotency-Keystring

    Makes a retry safe: for 24 hours, the same request with the same key returns the first response instead of repeating the change. Use 1 to 255 visible ASCII characters, without spaces, such as a UUID. See Idempotency.

    1 to 255 characters

Request body

application/jsonrequired
  • statestringrequired

    approved shows the content in the portal. rejected shows it only to its author and your team.

    One ofapprovedrejected

Responses

  • 200
    OKThe moderated post object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X POST \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "approved"
  }' \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/moderation"
Response · 200 OK
{
  "id": "post_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "name": "Dana Kim"
  },
  "board_id": "board_01h455vb4pex5vsknk084sn02q",
  "body_html": "<p>Finance exports every report by hand.</p>",
  "body_md": "Finance exports every report by hand.",
  "comment_count": 3,
  "customer_value": 1250000,
  "language": "en",
  "merged_into_id": null,
  "moderation_flags": [],
  "moderation_state": "approved",
  "number": 42,
  "slug": "export-reports-to-csv",
  "source": "api",
  "status": "planned",
  "tags": [
    {
      "id": "tag_01h455vb4pex5vsknk084sn02q",
      "scope": "post",
      "name": "Reporting",
      "color": "#3b82f6",
      "source": "manual",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "title": "Export reports to CSV",
  "translation": null,
  "visibility": "public",
  "vote_count": 17,
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": null,
  "status_changed_at": "2026-09-28T14:03:12.482Z"
}

Approve or reject a comment#

POST/v1/workspaces/{workspace_id}/comments/{comment_id}/moderation

An API key with Read and write access

An approved comment shows in the portal and counts on its post. A rejected comment shows only to its author and your team. Internal notes aren't moderated (422 not_moderatable).

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • comment_idstringrequired

    The comment's id.

    Starts with comment_

Headers

  • Idempotency-Keystring

    Makes a retry safe: for 24 hours, the same request with the same key returns the first response instead of repeating the change. Use 1 to 255 visible ASCII characters, without spaces, such as a UUID. See Idempotency.

    1 to 255 characters

Request body

application/jsonrequired
  • statestringrequired

    approved shows the content in the portal. rejected shows it only to its author and your team.

    One ofapprovedrejected

Responses

Example

Request
curl -X POST \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "approved"
  }' \
  "$SWINGBACK_API/comments/comment_01h455vb4pex5vsknk084sn02q/moderation"
Response · 200 OK
{
  "id": "comment_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn04s",
    "avatar_url": null,
    "email": "lee@example.com",
    "external_id": "u-9031",
    "kind": "user",
    "name": "Lee Park"
  },
  "body_html": "<p>We need this for quarterly reports too.</p>",
  "body_md": "We need this for quarterly reports too.",
  "heart_count": 2,
  "hearted": false,
  "language": "en",
  "mentions": [],
  "moderation_flags": [],
  "moderation_state": "approved",
  "parent_id": null,
  "post_id": "post_01h455vb4pex5vsknk084sn02q",
  "source": "api",
  "translation": null,
  "visibility": "public",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": null,
  "pinned_at": null
}

Ban an end user#

PUT/v1/workspaces/{workspace_id}/end-users/{end_user_id}/ban

An API key with Read and write access

A banned end user can still read the portal, but everything they write there (posts, comments, votes, follows, likes and uploads) returns 403 banned. A team member can't be banned (422 cannot_ban_team). Banning an end user again changes nothing.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • end_user_idstringrequired

    The end user's id.

    Starts with user_

Responses

Example

Request
curl -X PUT \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/end-users/user_01h455vb4pex5vsknk084sn02q/ban"
Response · 200 OK
{
  "id": "user_01h455vb4pex5vsknk084sn02q",
  "avatar_url": null,
  "companies": [
    {
      "id": "company_01h455vb4pex5vsknk084sn02q",
      "external_id": "acme",
      "name": "Acme",
      "value": 120000
    }
  ],
  "email": "dana@example.com",
  "external_id": "u-8412",
  "kind": "user",
  "name": "Dana Kim",
  "traits": {
    "plan": "enterprise",
    "seats": 40
  },
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "banned_at": "2026-10-02T09:30:00.000Z",
  "email_verified_at": null,
  "erased_at": null
}

Unban an end user#

DELETE/v1/workspaces/{workspace_id}/end-users/{end_user_id}/ban

An API key with Read and write access

Lifts the ban, so the end user can write in the portal again. Unbanning again changes nothing.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • end_user_idstringrequired

    The end user's id.

    Starts with user_

Responses

Example

Request
curl -X DELETE \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/end-users/user_01h455vb4pex5vsknk084sn02q/ban"
Response · 200 OK
{
  "id": "user_01h455vb4pex5vsknk084sn02q",
  "avatar_url": null,
  "companies": [
    {
      "id": "company_01h455vb4pex5vsknk084sn02q",
      "external_id": "acme",
      "name": "Acme",
      "value": 120000
    }
  ],
  "email": "dana@example.com",
  "external_id": "u-8412",
  "kind": "user",
  "name": "Dana Kim",
  "traits": {
    "plan": "enterprise",
    "seats": 40
  },
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "banned_at": null,
  "email_verified_at": null,
  "erased_at": null
}

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