# AutoSocial

AutoSocial is a social-media content production & operations workstation. From a
single REST surface an AI agent / script can generate platform-native posts
(text + optional AI image/video), publish them to connected accounts, and
schedule recurring publishing. This file tells an LLM / agent exactly how to
call it.

Full machine-readable API schema is at `https://auto-social.i-click.com/openapi.json`; a browsable UI is
at `https://auto-social.i-click.com/docs` (Swagger) and `https://auto-social.i-click.com/redoc`. All API paths below are relative
to the base URL `https://auto-social.i-click.com`.

## Authentication

All programmatic access uses a MIA platform Personal Access Token (PAT) prefixed
with `mia_pat_`.

1. Sign in to the MIA platform account page at https://mia-platform.i-click.com/account.
2. Create a Personal Access Token (PAT). The raw token is shown only once — store
   it securely. One PAT works across every MIA product line.
3. Send it on every request via the Authorization header:

    Authorization: Bearer mia_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

A PAT is bound to the MIA platform account that created it: requests run as that
user and consume that user's credit balance. No other headers are required.

## MCP

An MCP server is exposed at `https://auto-social.i-click.com/mcp` using the same
`Authorization: Bearer mia_pat_…` header. Point an MCP-capable agent there to
call the AutoSocial agent tools (generate / publish / schedule) directly over MCP.

## Async task model

Content generation is asynchronous:

1. `POST /api/v1/generate` → returns `{"batch_id", "items":[{"id","platform","status":"generating"}], "poll"}`.
2. Poll `GET /api/v1/generate/{item_id}` until `status` is `ready` or `failed`.
   Statuses: `generating` → `ready` / `failed`.
3. On `ready`, read `text` (the post copy) and `media_assets[].url` (AI image/video;
   a media asset may still be `processing` briefly after text is ready).
4. Publish it with `POST /api/v1/publish` (content_id + account_id), or schedule
   recurring generation/publishing with `POST /api/v1/schedule`.

----------------------------------------------------------------------
## 1) Generate  —  POST /api/v1/generate

Create one platform-native post (async). For multiple platforms, call once per
platform.

Request body (JSON):
  - `platform` (string; required) — target platform key (see list below).
  - `platforms` (array; optional legacy) — first item is used if `platform` unset.
  - `prompt` (string; required, 1–4000) — the theme / brief for the copy.
  - `account` (string; optional) — a connected account handle; injects that
    account's historical writing style.
  - `skill_id` (string; optional) — writing-style skill, e.g. `writer-seeding`
    or `user:<uuid>` for a custom style.
  - `media` (object; optional) — AI media (image and video are mutually
    exclusive; per-platform caps apply):
      `{"image": {"enabled": true, "count": 1}, "video": {"enabled": false, "duration": 8},
        "source_media_asset_ids": []}`
      - `media.source_media_asset_ids` (array of strings; optional) — asset ids of
        uploaded reference images for image-to-image (i2i) generation; when set,
        AI image generation is guided by these source images instead of pure
        text-to-image.
  - `web_search` (string; optional) — `off` | `auto` (default) | `on`.
  - `idempotency_key` (string; optional).

Response: `{"batch_id", "items":[{"id","platform","status"}], "status", "poll"}`.

Poll:  `GET /api/v1/generate/{item_id}` →
  `{"id","platform","status","text","error","media_assets":[{"url","kind","status"}], ...}`.

Minimal example:
  curl -X POST https://auto-social.i-click.com/api/v1/generate \
    -H "Authorization: Bearer mia_pat_..." -H "Content-Type: application/json" \
    -d '{"platform":"xiaohongshu","prompt":"a cozy autumn coffee ritual",
         "media":{"image":{"enabled":true,"count":1}}}'
  # → {"batch_id":"...","items":[{"id":"...","platform":"xiaohongshu","status":"generating"}],"poll":"/api/v1/generate/..."}
  # then poll GET /api/v1/generate/{id} until status=ready.

----------------------------------------------------------------------
## 2) Publish  —  POST /api/v1/publish

Publish an already-generated content item to a connected account (runs the real
dispatch pipeline; charges publishing usage on success).

Request body (JSON):
  - `content_id` (string; required) — the `id` from a generated item.
  - `account_id` (string; required) — the target connected account id.

Response: `{"ok": true, "content_id", "post_url"}` on success, or
`{"ok": false, "content_id", "error"}` (400) — honest error (`noaccount`,
`notoken`, `unsupported`, or the dispatch failure message).

  curl -X POST https://auto-social.i-click.com/api/v1/publish \
    -H "Authorization: Bearer mia_pat_..." -H "Content-Type: application/json" \
    -d '{"content_id":"...","account_id":"..."}'

----------------------------------------------------------------------
## 3) Schedule  —  POST /api/v1/schedule

Create a recurring generation (and optional publishing) job.

Request body (JSON):
  - `platform` (string; required), `prompt` (string; required, 1–4000).
  - `mode` — `generate` (default) | `generate_publish` (needs `account_id`).
  - `recurrence` — `once` (default) | `daily` | `weekly` | `monthly` | `interval` | `times`.
  - `weekly_days` — array of 0–6 (weekly).  `run_date` — ISO date (once).
  - `window_start` / `window_end` — `HH:MM` (default 09:00).
  - `interval_minutes` — int ≥ 5 (interval).  `daily_times` — array of `HH:MM` (times).
  - `skill_id`, `image_skill_id`, `media`, `account_id`, `web_search`, `name` — optional.

Response: `{"ok": true, "id": "<job uuid>"}`.

Helper — natural language to schedule fields:
  `POST /api/v1/schedule/parse-nl`  body `{"text": "every morning at 9am"}` →
  returns a field dict you can merge into the `POST /api/v1/schedule` body.

----------------------------------------------------------------------
## Platforms

Supported platform keys (use these as `platform`):

  - `baijiahao` — 百度百家号
  - `douyin` — 抖音
  - `facebook` — Facebook
  - `instagram` — Instagram
  - `ithome` — IT之家
  - `linkedin` — LinkedIn
  - `netease163` — 网易163
  - `official_site` — 官网博客
  - `phoenix` — 凤凰网大风号
  - `reddit` — Reddit
  - `sohu` — 搜狐号
  - `threads` — Threads
  - `twitter` — Twitter/X
  - `wechat_moments` — 微信朋友圈
  - `wechat_official` — 微信公众号
  - `weibo` — 微博
  - `xiaohongshu` — 小红书
  - `youtube` — YouTube
  - `zhihu` — 知乎

Aliases are normalized (e.g. `tiktok`→`douyin`, `x`→`twitter`, `xhs`→`xiaohongshu`).
See `GET /api/v1/platforms` for the full per-platform capability profile, and
`GET /api/v1/dispatch/capabilities` for which platforms can currently publish.
`GET /api/v1/skills` lists writing-style / media skills usable as `skill_id`.

## Billing & quota

Usage is metered in credits: 1 credit = $0.01 USD. A PAT spends its owner's
balance. `GET /api/v1/billing/quota` returns the current balance
(`availableCents` / `heldCents` / `usedCents`, plus a local `generationRemaining`
when the platform ledger is disabled). Generation reserves credits up front and
settles on completion; publishing charges on success.

## HTTP status codes

  - 200 — success (task created / fetched).
  - 400 — bad request (missing/invalid fields, publish failure).
  - 401 — missing/invalid PAT.
  - 402 — insufficient credit balance (redirect envelope with a top-up link).
  - 404 — item or path not found.
  - 422 — request body failed validation.
  - 503 — database / billing backend temporarily unavailable; retry with backoff.

See `https://auto-social.i-click.com/docs` for the complete, always-current OpenAPI specification.