Swell APICreate key

Manage Swell from your own tools.

Create content, schedule posts, generate tracked links, inspect connected accounts, and pull analytics with scoped API keys.

OpenAPI spec
Base URL
Production customer API
https://api.growonswell.com/v1

Quick Start

1

Create a key

Open Account Settings, choose API keys, and create a read/write token.

2

Call the API

Send the token as an Authorization bearer token to api.growonswell.com.

3

Use returned IDs

Use social_account_ids, media_ids, post IDs, and tracked link IDs in later calls.

Authentication

API keys belong to one workspace and can be revoked from Account Settings. Store the full key in your secret manager; Swell only shows it once.

Authorization: Bearer $SWELL_API_KEY
Available scopes
workspace:readaccounts:readmedia:readmedia:writeposts:readposts:writelinks:readlinks:writeanalytics:read

Rate Limits

Successful API responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. When a key is over its window, Swell returns 429 with `Retry-After`.

X-RateLimit-Remaining: 128Retry-After: 42

OpenAPI Contract

The customer API publishes a filtered OpenAPI document that excludes internal app routes and includes bearer-token security metadata for the public `/v1` surface.

https://api.growonswell.com/v1/openapi.jsonView spec

Endpoint Reference

Workspace

GET/workspace
Current workspace

Read workspace identity, slug, timezone, and plan key for the API key.

workspace:read
GET/social-accounts
Connected accounts

List the social accounts available for programmatic content and scheduling.

accounts:read

Content

GET/posts
List posts

Return recent posts. Add status=draft, scheduled, published, failed, or archived to filter, and limit up to 200.

posts:read
POST/posts
Create a post

Create a draft with caption, tags, media IDs, social account IDs, and platform overrides.

posts:write
GET/posts/{post_id}
Get a post

Read one workspace post by ID, including schedule, targets, media, tags, and publishing state.

posts:read
PATCH/posts/{post_id}
Update a post

Edit a draft or scheduled post using the same fields as the app composer.

posts:write
POST/posts/{post_id}/schedule
Schedule a post

Queue a draft for future publishing after the same validation used in the app.

posts:write
POST/posts/{post_id}/reschedule
Reschedule a post

Move a scheduled or failed post to a new future publish time.

posts:write
POST/posts/{post_id}/unschedule
Unschedule a post

Clear a scheduled post and return it to draft status.

posts:write
POST/posts/{post_id}/archive
Archive a post

Archive a draft, scheduled, or failed post without deleting its history.

posts:write

Media

GET/media
List media assets

Return recent images and videos that can be attached to API-created posts.

media:read
POST/media
Upload media

Upload a JPG, PNG, MP4, or MOV asset with optional alt text.

media:write
GET/media/{media_id}/file
Download media

Fetch the stored media bytes for a workspace asset.

media:read

Campaigns

GET/links
List tracked links

Read tracked links with destination URLs, tracking URLs, and attribution keys.

links:read
POST/links
Create a tracked link

Create a campaign link with UTM fields and optional post or social account context.

links:write

Analytics

GET/analytics/overview
Web analytics overview

Read visitors, pageviews, conversions, revenue, sources, pages, performance, and recent events.

analytics:read

Examples

Create a draft

curl -X POST "https://api.growonswell.com/v1/posts" \
  -H "Authorization: Bearer $SWELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch proof carousel",
    "base_caption": "A customer story with one clear next step.",
    "scheduled_at": null,
    "tags": ["launch", "customer-story"],
    "media_ids": [],
    "social_account_ids": [123],
    "platform_captions": {
      "linkedin": "A customer story with one clear next step."
    }
  }'

Upload media

curl -X POST "https://api.growonswell.com/v1/media" \
  -H "Authorization: Bearer $SWELL_API_KEY" \
  -F "file=@launch-image.png;type=image/png" \
  -F "alt_text=A product dashboard with a clean launch report."

Schedule a post

curl -X POST "https://api.growonswell.com/v1/posts/42/schedule" \
  -H "Authorization: Bearer $SWELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "2026-07-02T14:30:00Z"}'

Create a tracked link

curl -X POST "https://api.growonswell.com/v1/links" \
  -H "Authorization: Bearer $SWELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Summer launch",
    "destination_url": "https://example.com/summer",
    "utm_source": "linkedin",
    "utm_medium": "organic",
    "utm_campaign": "summer_launch",
    "utm_content": "carousel"
  }'

Errors

401 means the API key is missing, malformed, revoked, or invalid.

402 means the key owner must select a plan before making API calls.

403 means the key lacks the required scope or the key owner no longer has workspace access.

429 means the key exceeded its rate limit. Wait the number of seconds in `Retry-After` before retrying.

422 means the payload failed Swell validation, such as an unavailable social account or a past scheduled time.