Introduction

The Soku API is a REST API that gives you full programmatic access to Soku’s publishing, media management, template rendering, transcription, and automation features. Use it to integrate Soku into your own applications, build custom workflows, or automate content operations server-to-server.

Base URL

All API requests are made to the following base URL:

https://api.mysoku.io

Every endpoint path is prefixed with a version number. The current version is v1.

https://api.mysoku.io/v1/posts
https://api.mysoku.io/v1/media
https://api.mysoku.io/v1/templates
https://api.mysoku.io/v1/ai/transcribe

Authentication

The Soku API uses two authentication methods depending on the type of endpoint you are calling:

Auth Method	Header	Used For
API Key	`soku-api-key: sk_live_xxxxx`	All content endpoints (posts, media, templates, transcription)
ID Token	`Authorization: Bearer {firebase_id_token}`	API key management and metrics endpoints only

Most developers only need API key authentication. You can create and manage API keys from the Soku dashboard under Settings > API Keys.

curl -X POST https://api.mysoku.io/v1/posts \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{ "post": { "content": { "text": "Hello from the API" } } }'

Do not confuse the two authentication methods. Content endpoints use the soku-api-key header, not Authorization: Bearer. Using the wrong header will result in a 401 Unauthorized error.

For full details on obtaining and securing your API key, see Authentication.

Subscription Required

All content API calls require an active Soku subscription. Your account must be in either a trialing or active subscription state. If your subscription has expired or been canceled, API requests will return a 403 Forbidden error.

Available Endpoints

Content Endpoints (API Key Auth)

Endpoint	Method	Description
`/v1/posts`	POST	Create and submit a post to one or more platforms
`/v1/media`	POST	Upload remote media to the Soku media library
`/v1/media/render-og`	POST	Render an OG image template (alias for `/v1/templates`)
`/v1/templates`	POST	Render an OG image template
`/v1/ai/transcribe`	POST	Transcribe audio or video content using AI

Key Management Endpoints (ID Token Auth)

Endpoint	Method	Description
`/v1/api-keys`	POST	Create an API key
`/v1/api-keys`	GET	List API keys
`/v1/api-keys/{id}`	DELETE	Revoke an API key

Other Endpoints (ID Token Auth)

Endpoint	Method	Description
`/v1/metrics/refresh`	POST	Refresh account metrics

Request Format

All request bodies must be sent as JSON with the Content-Type: application/json header.

curl -X POST https://api.mysoku.io/v1/posts \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -H "Idempotency-Key: optional-unique-key" \
  -d '{
    "post": {
      "content": {
        "text": "Published via the Soku API",
        "mediaType": "text",
        "platform": ["threads"]
      }
    }
  }'

Response Format

All responses are returned as JSON. Successful responses include the relevant resource data. Error responses follow a consistent structure with an error object containing a machine-readable type, a code, a human-readable message, a timestamp, and a requestId for support correlation. Successful response:

{
  "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Error response:

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Request validation failed",
    "timestamp": "2026-02-28T12:00:00.000Z",
    "requestId": "req_abc123def456",
    "details": null
  }
}

Request Tracking

Every API response includes an X-Request-ID header. This value uniquely identifies your request and can be used when contacting support to help diagnose issues.

X-Request-ID: req_abc123def456

You can also send your own X-Request-ID header with a request. If provided, the API will use your value for correlation instead of generating one.

Rate Limits

API requests are subject to rate limits based on your authentication and subscription tier. Authenticated users with an active subscription (Premium tier) receive up to 100 requests per minute. Individual endpoints may have lower limits. See Rate Limits for details. Rate limit information is included in every response via the X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-Tier headers.

For details on rate limit tiers, burst allowances, endpoint-specific limits, and best practices, see Rate Limits.

Idempotency

The following endpoints support idempotent requests via the Idempotency-Key header:

POST /v1/posts
POST /v1/media
POST /v1/ai/transcribe

If you omit the Idempotency-Key header, Soku auto-derives a key from your user ID and a hash of the request payload. Sending the same idempotency key with the same request body returns the cached original response. Sending the same key with a different body returns a 409 Conflict error.

Supported Platforms

The Soku API supports publishing to the following social media platforms:

Platform	Value
Facebook (personal)	`facebook`
Facebook Pages	`facebook_pages`
Instagram	`instagram`
Threads	`threads`
TikTok	`tiktok`
YouTube	`youtube`
X (Twitter)	`x`
LinkedIn	`linkedin`
Snapchat	`snapchat`

Quick Start Example

The following example creates a text post on Threads and X simultaneously:

curl -X POST https://api.mysoku.io/v1/posts \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{
    "post": {
      "content": {
        "text": "Excited to announce our new feature launch!",
        "mediaType": "text",
        "platform": ["threads", "x"]
      }
    }
  }'

Response:

{
  "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Next Steps

Topic	Description
Authentication	Learn about both authentication methods and API key security
Posts API	Create and publish posts to social platforms
Media API	Upload media for use in posts
Code Examples	Complete workflow examples in curl, JavaScript, and Python
Error Handling	Understand error codes and troubleshooting

​Introduction

​Base URL

​Authentication

​Subscription Required

​Available Endpoints

​Content Endpoints (API Key Auth)

​Key Management Endpoints (ID Token Auth)

​Other Endpoints (ID Token Auth)

​Request Format

​Response Format

​Request Tracking

​Rate Limits

​Idempotency

​Supported Platforms

​Quick Start Example

​Next Steps

Introduction

Base URL

Authentication

Subscription Required

Available Endpoints

Content Endpoints (API Key Auth)

Key Management Endpoints (ID Token Auth)

Other Endpoints (ID Token Auth)

Request Format

Response Format

Request Tracking

Rate Limits

Idempotency

Supported Platforms

Quick Start Example

Next Steps