Skip to main content

Publish via Public API v1

Quick links: Public API • Data Model

Prerequisites​

  • Create an API key in the web app (Settings → API Keys) or call POST /api/api-keys with a valid session.
  • Export it to your shell: export SOKU_API_KEY=sk_live_...

Submit a text post to X and Threads​

curl -X POST "https://<region>-<project>.cloudfunctions.net/api/v1/posts" \
  -H "Content-Type: application/json" \
  -H "soku-api-key: $SOKU_API_KEY" \
  -d '{
    "post": {
      "content": {
        "text": "Shipping update via Sokuho",
        "platform": [
          { "platform": "x", "accountId": "x_primary" },
          "threads"
        ]
      }
    }
  }'

Response contains postSubmissionId. Inspect progress in Firestore under postSubmissions/{id} and runs/*.

Account targeting: If a platform has more than one connected account, every array entry must include both platform and accountId. Requests that omit accountId are rejected with 400 missing_account.

Upload remote media and post to Instagram​

MEDIA_URL=$(curl -s -X POST "https://<region>-<project>.cloudfunctions.net/api/v1/media" \
  -H "Content-Type: application/json" \
  -H "soku-api-key: $SOKU_API_KEY" \
  -d '{ "url": "https://picsum.photos/seed/soku/1080/1350.jpg" }' | jq -r .url)

curl -X POST "https://<region>-<project>.cloudfunctions.net/api/v1/posts" \
  -H "Content-Type: application/json" \
  -H "soku-api-key: $SOKU_API_KEY" \
  -d "{\n  \"post\": {\n    \"content\": {\n      \"text\": \"IG post from API\",\n      \"mediaUrls\": [\"$MEDIA_URL\"],\n      \"platform\": [{ \"platform\": \"instagram\", \"accountId\": \"ig_creator_main\" }]\n    }\n  }\n}"

Schedule a future publish​

curl -X POST "https://<region>-<project>.cloudfunctions.net/api/v1/posts" \
  -H "Content-Type: application/json" \
  -H "soku-api-key: $SOKU_API_KEY" \
  -d '{
    "post": { "content": { "text": "Scheduled post", "platform": ["x"] } },
    "scheduledTime": "2030-01-01T12:00:00Z"
  }'

Troubleshooting​

  • 401 unauthorized → Check soku-api-key header and that the key is not revoked.
  • 400 bad_request → Ensure required fields exist (e.g., text for X/Threads, mediaUrls[0] for Instagram).
  • Inspect users/{uid}/apiRequests for request logs and postSubmissions/* for run statuses.