Menu

SocialEcho OpenAPI Documentation

1. Intended Audience

This document is for R&D, QA, implementation, and automation engineers who integrate with the SocialEcho external API. The goal is a working integration in the shortest possible time.

2. Quick Start (3 minutes)

  1. Log in to https://app.socialecho.net and create a team.

  2. In Team Management, create a Team API Key.

  3. Call APIs using Bearer authentication (Authorization: Bearer se_xxx).

  4. Call GET /v1/team first to verify auth and team context, then call other endpoints.

  5. Use the success criteria in Environment & Authentication below.

3. Environment & Authentication

Field

Description

Base URL

https://api.socialecho.net

Authentication

Bearer Token (Team API Key)

Header

Authorization: Bearer se_your_team_api_key

Optional header

X-Lang: zh_CN or en

Rate limit

120 requests per minute per API key

3.1 Transport shape (difference from older help examples)

The exported OpenAPI defines many operations as **GET with a JSON request body** (Content-Type: application/json), not query-string parameters.
Some HTTP clients (e.g. browser fetch) restrict GET bodies; prefer curl, server-side HTTP libraries, or the provided CLI / n8n node.

3.2 Recommended success criteria

  1. HTTP status code = 200

  2. JSON field **code is 200 or 0** (follow the live API; older docs only mentioned 200)

  3. Anything else → treat as failure and retry/alert

4. Common Error Handling

Case

Meaning & action

400 Bad Request

Missing or malformed parameters (check dates and enums first)

401 Unauthorized

Invalid/expired API key, or wrong Authorization header

429 Too Many Requests

Rate limited – add throttling and exponential backoff (1s/2s/4s)

Timeout / network

Retry 2–3 times; keep a snapshot of request parameters

5. API Endpoints

Examples use Base URL https://api.socialecho.net. Replace se_your_team_api_key with your Team API Key.

curl note: for GET with JSON body, use --data-raw '<json>' and set Content-Type: application/json.

5.1 Get team information (GET /v1/team)

Call this first to confirm team context.

Parameter

In

Required

Type

Description

X-Lang

header

No

string

zh_CN or en (default zh_CN)

body

body

No

object

Empty object {}

cURL

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: zh_CN' \
  --data-raw '{}'

Response example

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1024,
    "code": "TEAM_ABC123",
    "title": "SocialEcho QA Team",
    "timezone": "Asia/Shanghai"
  }
}

5.2 List social accounts (GET /v1/account)

Parameter

In

Required

Type

Description

X-Lang

header

No

string

Response language

page

body

No

integer

Page number

type

body

No

integer

1 = authorized account, 2 = competitor

cURL

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: zh_CN' \
  --data-raw '{"page":1,"type":1}'

Response example

{
  "code": 200,
  "message": "success",
  "data": {
    "page": 1,
    "per_page": 10,
    "total": 2,
    "list": [
      {
        "id": 163751,
        "title": "esprit.vert.medic",
        "app": "Instagram",
        "type": 1,
        "status": "normal",
        "account": "@esprit.vert.medic",
        "authorization_at": "2026-03-30 09:34:44"
      }
    ]
  }
}

5.3 List posts (GET /v1/article)

Parameter

In

Required

Type

Description

X-Lang

header

No

string

Response language

page

body

No

integer

Page number

account_ids

body

No

integer[]

Account ID array

cURL

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: zh_CN' \
  --data-raw '{"page":1,"account_ids":[163956,163955,28]}'

Response example

{
  "code": 200,
  "message": "success",
  "data": {
    "page": 1,
    "per_page": 10,
    "total": 1,
    "list": [
      {
        "id": 987654,
        "uuid": "tE-9LwdHfNk",
        "app": "YouTube",
        "account_id": 163751,
        "content": "Example article content",
        "created_at": "2026-03-24 10:05:01",
        "url": "https://www.youtube.com/watch?v=tE-9LwdHfNk",
        "reports": {
          "exposure": 1021,
          "like": 40,
          "comment": 14,
          "share": 0
        }
      }
    ]
  }
}

5.4 Report data (GET /v1/report)

Parameter

In

Required

Type

Description

X-Lang

header

No

string

Response language

start_date

body

Yes

string

YYYY-MM-DD

end_date

body

Yes

string

YYYY-MM-DD

time_type

body

Yes

integer

1 = new posts in range, 2 = all historical posts in range

account_ids

body

No

integer[]

Account IDs

group

body

No

string

Empty = totals; day / app / account for grouping

cURL

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: zh_CN' \
  --data-raw '{"start_date":"2026-01-01","end_date":"2026-03-24","time_type":1,"group":"day","account_ids":[163956,163955,28]}'

Response example (totals)

{
  "code": 200,
  "message": "success",
  "data": {
    "scope": {
      "start_date": "2026-01-01",
      "end_date": "2026-03-24",
      "time_type": 1,
      "group": ""
    },
    "totals": {
      "exposure": 120345,
      "like": 4512,
      "comment": 893,
      "share": 326
    }
  }
}

5.5 Get OSS upload URL (GET /v1/upload/url)

Returns upload URL information for OSS (exact payload is server-defined). Typical flow: get upload URL → upload file → use returned file URL in attachments for publish.

Parameter

In

Required

Type

Description

X-Lang

header

No

string

Response language

body

body

No

object

Empty object {}

cURL

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: zh_CN' \
  --data-raw '{}'

5.6 List Reddit communities (GET /v1/reddit/communities)

Used before publishing to Reddit to pick community context.

Parameter

In

Required

Type

Description

X-Lang

header

No

string

Response language

account_id

body

Yes

integer

Social account id

cURL

curl --request GET 'https://api.socialecho.net/v1/reddit/communities' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"account_id":163751}'

5.7 List Pinterest boards (GET /v1/pinterest/boards)

Used before publishing to Pinterest to pick a board.

Parameter

In

Required

Type

Description

X-Lang

header

No

string

Response language

account_id

body

Yes

integer

Social account id

cURL

curl --request GET 'https://api.socialecho.net/v1/pinterest/boards' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"account_id":163751}'

5.8 Publish a post (POST /v1/publish/article)

Cross-platform publishing. Fields type, extra, and attachments are platform-specific; validate in the product UI and integration tests. The following summarizes core OpenAPI fields.

Parameter

In

Required

Type

Description

X-Lang

header

No

string

Response language

account_id

body

Yes

integer

Target social account

type

body

Yes

string

Publish type (per platform, e.g. Facebook post, YouTube video)

status

body

Yes

integer

0 = draft, 1 = publish

scheduled_at

body

No

string

Schedule time; if status=1 and omitted, publish immediately

comment

body

Yes

string[]

Comments array (may be empty)

content

body

No

string

Body text

extra

body

Yes

object

Platform extras: title, board/community id, link, TikTok draft flag, Reddit flair, etc.

attachments

body

Yes

object[]

Attachments; each item must include an uploaded file URL: { "url": "https://..." }

Examples of type (from OpenAPI)
Facebook: reels / post / stories; YouTube: shorts / video; Instagram: reels / post / stories; X: short_post / long_post; LinkedIn: post; TikTok: video / photo; Pinterest: post; Reddit: text / link / media.

cURL (use a real JSON file)

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: zh_CN' \
  --data @publish-payload.json

publish-payload.example.json：
{
  "account_id": 123456,
  "type": "post",
  "status": 0,
  "scheduled_at": "",
  "comment": [],
  "content": "example-content",
  "extra": {
    "title": "example-title",
    "category_id": "",
    "link": "",
    "draft": false,
    "flair": {
      "uuid": "replace-with-reddit-flair-uuid",
      "title": "replace-with-reddit-flair-title"
    }
  },
  "attachments": [
    {
      "url": "https://example.com/uploaded-file.jpg"
    }
  ]
}
 

Fill extra for the target platform (e.g. Pinterest category_id, Reddit flair). A starter example exists as publish-payload.example.json in the skills package repository.

6. Integration Recommendations

  1. Fetch accounts first, then pass account_id into posts, reports, Reddit, Pinterest, etc.

  2. For paginated APIs, loop page until the last page using total / per_page.

  3. In workflow tools (n8n, Zapier, Dify), separate auth errors from rate-limit errors.

  4. Log request time, endpoint, HTTP status, business code, and key request parameters for troubleshooting.

  5. For publishing, prefer **GET /v1/upload/url** then assemble attachments.

7. FAQ

Q1: HTTP 200 but business failure?
A: Trust JSON **code is 200 or 0**, not HTTP alone.

Q2: How to pass account_ids in JSON?
A: Use an integer array (e.g. [163956,163955,28]). If you still use CSV query parameters from an old integration, migrate to the OpenAPI body shape.

Q3: How to avoid 429?
A: Stay under 120 req/min per key; add throttling and exponential backoff.

This local document aligns with the help-center structure and with 默认模块.openapi.json (v1.1.0). If anything disagrees with the live service, trust the server and the latest exported OpenAPI.

Previous
API Documentation
Next
Platform publish limits: copy, media, and formats (reference)
Last modified: 2026-04-21Powered by