# SocialEcho OpenAPI - Developer LLM Reference

This machine-readable document targets developers, testers, implementers, automation engineers, and AI agents integrating the SocialEcho OpenAPI.

- Developer LLM: https://www.socialecho.net/llms-developers.txt
- Official developer docs: https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs
- API Base URL: https://api.socialecho.net
- Source verified: 2026-08-24 (official docs updated 2026-08-11)

## Quickstart

1. Sign in at https://app.socialecho.net and create or select a team.
2. Create a Team API Key in team management (keys are prefixed `se_`).
3. Add `Authorization: Bearer se_your_team_api_key` to every request.
4. Call `GET /v1/team` first to verify authentication and team context.
5. Judge results by HTTP status code first, then the business `code` in the response body.
6. Fetch account IDs via `GET /v1/account` before querying posts, reports, publishing, or platform-specific resources.

## Authentication & Transport

- Auth: Bearer token using a Team API Key.
- Auth header: `Authorization: Bearer se_your_team_api_key`.
- JSON requests: `Content-Type: application/json`.
- Optional language header: `X-Lang: zh_CN` or `X-Lang: en` (default zh_CN).
- Optional tracing: send `X-Request-Id`; the server also returns an `X-Request-Id` header.
- Rate limit: 120 requests per minute per API Key.
- Never expose the Team API Key in browser code, public repositories, logs, or prompts sent to untrusted services.

Important transport rule: most GET endpoints take parameters in a JSON request body, not query strings. Browser `fetch` cannot reliably send GET bodies — use cURL, a server-side HTTP client, the SocialEcho CLI, or a supported automation connector such as the n8n node. TikTok Shop query endpoints also accept the same parameters as query strings.

## Response Envelope, Success Criteria & Error Handling

Uniform envelope: `code`, `message`, `data`, `request_id`; failures add an `error` object (`type`, `reason`, `suggestion`); paginated responses add `meta`.

A call is successful only when both hold:

- The HTTP status is `2xx`.
- The business `code` in the response JSON is `0`.

Failures use HTTP 4xx/5xx with business codes equal to HTTP status × 100:

- `400` / `40000`: bad request. Check required fields, dates, arrays, MIME types, and platform enums.
- `401` / `40100`: missing or invalid key. Check the Team API Key and Bearer header format.
- `403` / `40300`: no permission (e.g., no draft permission).
- `404` / `40400`: resource missing or not owned by the team.
- `405` / `40500`: wrong HTTP method.
- `409` / `40900`: state conflict.
- `413` / `41300`: payload too large.
- `419` / `41900`: authentication timeout.
- `422` / `42200`: validation failed or business precondition not met.
- `429` / `42900`: rate limit or sync cooldown (product sync responses include `data.next_allowed_at` or `Retry-After`).
- `500` / `50000`: server error.
- `502` / `50200`: upstream platform failure.
- `503`/`504` / `50300`/`50400`: service unavailable or gateway timeout.

Retry policy: auto-retry only `429`, `502`, `503`, `504`, and timeouts (exponential backoff at 1, 2, 4 seconds); fix the request or permissions first for everything else.

Known caveats:

- The upload endpoint currently returns HTTP `500` / `50000` for unsupported MIME types.
- A `422`/`500` at publish submission does not guarantee no record was created — verify via `GET /v1/article` before retrying to avoid duplicate posts.

## Available Endpoints (13 total)

### GET /v1/team

Returns the authenticated team (id, code, title, timezone). Call this first after configuring a key.

- Body: `{}` (optional)

```bash
curl --request GET 'https://api.socialecho.net/v1/team' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: en' \
  --data-raw '{}'
```

### GET /v1/account

Lists authorized or competitor accounts.

- `page`: optional integer page number.
- `type`: optional integer; `1` = authorized accounts, `2` = competitor accounts.

```bash
curl --request GET 'https://api.socialecho.net/v1/account' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"page":1,"type":1}'
```

### GET /v1/oauth/links

Returns per-platform OAuth authorization URLs for connecting new accounts. No business parameters.

- Returns: `data[].id`, `data[].title`, `data[].connections[].type`, `data[].connections[].url`.
- Platform IDs: Instagram 1, Facebook 2, TikTok 3, LinkedIn 4, YouTube 5, Telegram 6, X 7, Pinterest 8, Reddit 9, Threads 10, TikTokShop 11.
- Connection type examples: `seller`/`creator` for TikTokShop; `instagram`/`facebook` for Instagram.

### GET /v1/article

Lists posts for the team or specific accounts, including content, URL, and report metrics (exposure/likes/comments/shares).

- `page`: optional integer page number.
- `account_ids`: optional integer array of SocialEcho account IDs.

```bash
curl --request GET 'https://api.socialecho.net/v1/article' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"page":1,"account_ids":[163956,163955,28]}'
```

### GET /v1/report

Returns analytics for a date range.

- `start_date`: required string, `YYYY-MM-DD`.
- `end_date`: required string, `YYYY-MM-DD`.
- `time_type`: required integer; `1` = posts created in range, `2` = all historical posts measured in range.
- `account_ids`: optional integer array of account IDs.
- `group`: optional string; empty for aggregate, or `day`, `app`, `account`.

```bash
curl --request GET 'https://api.socialecho.net/v1/report' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"start_date":"2026-01-01","end_date":"2026-03-24","time_type":1,"group":"day","account_ids":[163956,163955,28]}'
```

### GET /v1/upload/url

Returns OSS presigned upload info. Flow: get the URL → `PUT` the file → use the returned `public_url` (not the time-limited `upload_url`) in publish `attachments`.

- `content_type`: required MIME type.
- `title`: optional string, up to 255 characters.
- Image types: `image/jpeg`, `image/jpg`, `image/png`, `image/gif`, `image/webp`, `image/bmp`.
- Video types: `video/mp4`, `video/avi`, `video/mov`, `video/wmv`, `video/flv`, `video/webm`, `video/mkv`, `video/3gp`, `video/quicktime`.

```bash
curl --request GET 'https://api.socialecho.net/v1/upload/url' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"content_type":"image/png"}'
```

### GET /v1/reddit/communities

Lists communities available to a connected account before publishing to Reddit.

- `account_id`: required integer SocialEcho account ID.

### GET /v1/pinterest/boards

Lists boards available to a connected account before publishing to Pinterest.

- `account_id`: required integer SocialEcho account ID.

### GET /v1/tiktokshop/products

Lists synced TikTok Shop products. `status = 1` means the product can be attached to a shoppable video.

- `account_id`: required integer.
- `page`: optional integer.
- `per_page`: optional integer, 1–100, default 20.
- `keyword`: optional string, up to 500 characters.

### POST /v1/tiktokshop/products/sync

Queues an asynchronous product refresh. "Queued" is not "completed" — confirm later via the product list.

- `account_id`: required integer.
- Cooldown: roughly 60 minutes per account; during cooldown the API returns `429` with `data.next_allowed_at` or `Retry-After`.

### GET /v1/tiktokshop/music/genres

Lists commercial music library genre values (e.g., `ALL`, `POP`, `BGM`). No business parameters.

### GET /v1/tiktokshop/music/trending

Returns trending commercial-library music with `uuid`, `title`, `artist`, `url`, `cover`, `duration`.

- `account_id`: required integer.
- `country_code`: optional string.
- `genre`: optional string (from the genre enum).
- `date_range`: optional string, `1DAY` / `7DAY` / `30DAY` / `90DAY`.

### POST /v1/publish/article

Creates a draft, publishes immediately, or schedules cross-platform content. Publishing itself is asynchronous — success means a publish record was created (returns `data.id`).

- `account_id`: required integer target account ID.
- `type`: required string, platform-specific publish type.
- `status`: required integer; `0` = draft, `1` = publish.
- `scheduled_at`: optional schedule time; with `status=1` and no schedule, publishes immediately.
- `comment`: required string array, may be empty.
- `content`: optional post body (required for TikTok Shop).
- `extra`: required object with platform-specific fields such as title, board or community ID, link, TikTok draft flag, Reddit flair.
- `attachments`: required object array; each item uses an uploaded file's `public_url`, e.g. `{ "url": "https://..." }`.

Common `type` values:

- Facebook: `reels`, `post`, `stories`.
- Instagram: `reels`, `post`, `stories`.
- YouTube: `shorts`, `video`.
- X: `short_post`, `long_post`.
- LinkedIn: `post`.
- TikTok: `video`, `photo`.
- TikTok Shop: `video`.
- Pinterest: `post`.
- Reddit: `text`, `link`, `media`.

TikTok Shop shoppable-video rules:

- `content` is required, up to 2200 UTF-16 code units.
- `extra.title` is required, up to 30 characters, letters/digits/spaces only.
- `extra.product` is required and must be copied verbatim from the product list response (`id`, `uuid`, `title`, `thumb`).
- `extra.music` is optional; if used it must contain all nine fields: `url`, `uuid`, `cover`, `title`, `artist`, `duration`, `selection`, `music_volume`, `original_sound_volume`; `selection` is `none` / `trending_clip` / `full_track`.
- Attachments: exactly one video, up to 500 MB.

```bash
curl --request POST 'https://api.socialecho.net/v1/publish/article' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --data @publish-payload.json
```

## Recommended Integration Flow

1. Verify the key and team via `GET /v1/team`.
2. Fetch authorized accounts via `GET /v1/account` and store the returned SocialEcho account IDs; use `GET /v1/oauth/links` to generate authorization URLs when connecting new accounts.
3. For paginated endpoints, keep incrementing `page` until `meta`'s `total` and `per_page` indicate the last page.
4. Before publishing media, call `GET /v1/upload/url`, `PUT` the file, and put the `public_url` into `attachments`.
5. Before publishing to Reddit or Pinterest, fetch communities or boards; before publishing a TikTok Shop shoppable video, sync and query products (and query music genres/trending if adding a soundtrack).
6. Send the final payload to `POST /v1/publish/article`.
7. Close the loop from publishing to analytics via `GET /v1/article` and `GET /v1/report`.

## Current API Scope

The public OpenAPI currently exposes 13 endpoints covering teams, accounts, OAuth authorization links, posts, reports, upload URLs, Reddit communities, Pinterest boards, TikTok Shop products and commercial music, and content publishing. The source docs do not list comment or DM endpoints, webhooks, or an official MCP server as live capabilities — do not assume they exist.

Platform-specific `extra` fields and publishing limits can change; treat the official docs as the source of truth: https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs