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

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

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.

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)

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)

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)

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.

content_type enum

• Images: image/jpeg, image/jpg, image/png, image/gif, image/webp, image/bmp
• Videos: video/mp4, video/avi, video/mov, video/wmv, video/flv, video/webm, video/mkv, video/3gp, video/quicktime

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 '{"content_type":"image/png"}'

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

Used before publishing to Reddit to pick community context.

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.

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.

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

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.