Threads FastAPI skill#

Use this skill whenever the user asks to generate, queue, schedule, or publish content to Threads.

Required environment variables (on the Gateway host)#

• THREADS_FASTAPI_BASE_URL (example: http://127.0.0.1:8000)
• THREADS_QUEUE_SECRET (the value to send as X-Queue-Secret, only for /threads/publish)
• Optional: THREADS_TENANT_ID (default: agency_paris)

If these are missing, ask the user for the correct values.

Storage options (backend-side)#

This skill does not store media itself. Storage is handled by the FastAPI backend.

Local Pack (demo / single machine)#

Set on the backend:

text

STORAGE_PROVIDER=local
UPLOADS_DIR=uploads
UPLOADS_PATH=/uploads

This stores uploads in UPLOADS_DIR and serves them from UPLOADS_PATH.

Cloud storage (prod)#

Set STORAGE_PROVIDER=cloudinary or s3 on the backend and configure the provider credentials there.

Endpoints (per your spec)#

• POST {BASE}/api/v1/threads/publish
  • Requires header X-Queue-Secret
• POST {BASE}/api/v1/assistant/chat
  • No queue secret header (unless your backend requires it later)

Both accept JSON.

How to call (safe)#

Use the HTTP tool in OpenClaw (not exec).

Send JSON directly to the FastAPI endpoint with the required headers.

Example:

• URL: {BASE}/api/v1/threads/publish
• Method: POST
• Headers: X-Queue-Secret: <THREADS_QUEUE_SECRET>
• Body: JSON payload (see below)

Payloads#

A) Publish / enqueue Threads post#

Call POST {BASE}/api/v1/threads/publish with:

json

{
  "message": "<message text>",
  "images": [],
  "scheduled_at": null,
  "publish_mode": "queue",
  "auto_proxy_images": true,
  "meta": {
    "tenant_id": "agency_paris",
    "source": "telegram",
    "chat_id": "<tg chat id>",
    "user_id": "<tg user id>",
    "username": "<tg username>"
  }
}

B) /postimg generate+enqueue via assistant#

Call POST {BASE}/api/v1/assistant/chat with:

json

{
  "session_id": "tg_<chat id>",
  "execute_tools": true,
  "message": "Generate and enqueue one image post",
  "context": {
    "tenant_id": "agency_paris",
    "prompt": "<tg args>",
    "message": "<tg args>",
    "provider": "replicate",
    "model": "black-forest-labs/flux-1.1-pro",
    "source": "telegram",
    "campaign": "remote_demo",
    "api_base_url": "http://127.0.0.1:8000"
  }
}

Note: The skill should fill tenant_id from THREADS_TENANT_ID when set.

Safety#

• Never forward secrets from chat into shell commands except as the -QueueSecret argument.
• Do not log the secret.
• Validate that BaseUrl is an http(s) URL.