# SocialEcho OpenAPI - Developer LLM Reference

This machine-readable reference is for developers, QA engineers, implementation teams, automation engineers, and AI agents integrating with the SocialEcho OpenAPI.

- Canonical developer LLM: https://www.socialecho.net/llms-developers.txt?lang=en
- Official human-readable documentation: https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs
- API base URL: https://api.socialecho.net
- Source last verified: 2026-07-16

## Quick Start

1. Sign in at https://app.socialecho.net and create or select a team.
2. Create a Team API Key in Team Management.
3. Send the key in `Authorization: Bearer se_your_team_api_key`.
4. Call `GET /v1/team` first to verify authentication and team context.
5. Fetch account IDs with `GET /v1/account` before requesting posts, reports, publishing, Reddit communities, or Pinterest boards.

## Authentication and Transport

- Authentication: Bearer Token using a Team API Key.
- Required auth header: `Authorization: Bearer se_your_team_api_key`.
- Content type for JSON requests: `Content-Type: application/json`.
- Optional response-language header: `X-Lang: zh_CN` or `X-Lang: en`.
- Rate limit: 120 requests per minute per API key.
- Never expose a Team API Key in browser code, public repositories, logs, or prompts sent to untrusted services.

Important transport behavior: several GET operations accept a JSON request body instead of query-string parameters. Browser `fetch` does not reliably support GET bodies, so use cURL, a server-side HTTP client, or a supported automation connector.

## Success and Error Handling

A request is successful only when both conditions are true:

- HTTP status is `200`.
- The response JSON field `code` is `200` or `0`.

Treat any other business code as a failure even when the HTTP response is `200`.

- `400 Bad Request`: validate required fields, dates, arrays, MIME types, and platform enums.
- `401 Unauthorized`: verify the Team API Key and the exact Bearer header format.
- `429 Too Many Requests`: throttle below 120 requests per minute and retry with exponential backoff such as 1, 2, and 4 seconds.
- Timeout or network failure: retry two or three times and log the endpoint, request time, HTTP status, business code, and non-sensitive request parameters.

## Available Endpoints

### GET /v1/team

Returns the authenticated team context. Call this first after configuring a key.

- Body: `{}` (optional)
- Optional header: `X-Lang`

```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 social accounts.

- `page`: optional integer page number.
- `type`: optional integer; `1` for authorized accounts and `2` for 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' \
  --header 'X-Lang: en' \
  --data-raw '{"page":1,"type":1}'
```

### GET /v1/article

Lists posts for the team or selected accounts.

- `page`: optional integer page number.
- `account_ids`: optional array of integer 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' \
  --header 'X-Lang: en' \
  --data-raw '{"page":1,"account_ids":[163956,163955,28]}'
```

### GET /v1/report

Returns analytics for a date range.

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

```bash
curl --request GET 'https://api.socialecho.net/v1/report' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: en' \
  --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 upload information for a media file. The usual publishing flow is: request an upload URL, upload the file, then pass the returned file URL in `attachments` when publishing.

- `content_type`: required MIME type.
- Image MIME types: `image/jpeg`, `image/jpg`, `image/png`, `image/gif`, `image/webp`, `image/bmp`.
- Video MIME 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' \
  --header 'X-Lang: en' \
  --data-raw '{"content_type":"image/png"}'
```

### GET /v1/reddit/communities

Lists Reddit communities available to a connected account before publishing.

- `account_id`: required integer SocialEcho account ID.

### GET /v1/pinterest/boards

Lists Pinterest boards available to a connected account before publishing.

- `account_id`: required integer SocialEcho account ID.

### POST /v1/publish/article

Creates a draft, publishes immediately, or schedules a cross-platform post. Platform-specific fields must be validated against the current product UI and official OpenAPI documentation.

- `account_id`: required integer target account ID.
- `type`: required platform-specific publish type.
- `status`: required integer; `0` for draft and `1` for publish.
- `scheduled_at`: optional schedule time; omit with `status=1` to publish immediately.
- `comment`: required string array; it may be empty.
- `content`: optional post text.
- `extra`: required object containing platform-specific values such as title, board or community ID, link, TikTok draft flag, or Reddit flair.
- `attachments`: required object array. Each item uses an uploaded media URL such as `{ "url": "https://..." }`.

Common `type` values documented by the OpenAPI:

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

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

## Recommended Integration Flow

1. Verify the key and team with `GET /v1/team`.
2. Fetch authorized accounts with `GET /v1/account` and persist the returned SocialEcho account IDs.
3. For paginated endpoints, increment `page` until the returned `total` and `per_page` indicate the final page.
4. For media publishing, call `GET /v1/upload/url`, upload the media, and use the resulting URL in `attachments`.
5. Fetch a Reddit community or Pinterest board before publishing to those platforms.
6. Send the final payload to `POST /v1/publish/article`.
7. Query `GET /v1/article` and `GET /v1/report` to close the workflow from publishing to analytics.

## Current API Scope

The current public OpenAPI covers team information, accounts, posts, reports, upload URLs, Reddit communities, Pinterest boards, and publishing. Comment and direct-message endpoints, as well as an official MCP server, are not listed as live endpoints in the source documentation and should not be assumed available.

For details that may change, including platform-specific `extra` fields and publishing restrictions, use the official documentation as the source of truth: https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs