# SocialEcho AI Agent API

> **🎁 Free during launch preview.** All endpoints below are live and callable. Grab a paid plan on the Pricing page, generate an `sk_live_` key from **System Settings → Team Info → API Key** in the dashboard, and you're ready to go.

**Key links**

- 📖 Full reference (upstream, partial OpenAPI): <https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs>
- 🧰 OpenClaw on ClawHub: <https://clawhub.ai/socialecho-net/social-media-autopilot-api>
- 💻 Open-source SDK on GitHub: <https://github.com/SocialEcho-net/social-media-autopilot>
- 🌐 Marketing page: <https://www.socialecho.net/product/ai-agents>

The SocialEcho AI Agent API is an HTTP/REST interface purpose-built for autonomous agents, LLM tool-calling frameworks, and no-code automation platforms. It exposes the three core domains of SocialEcho — **Publishing**, **Analytics**, and **Monitoring** — behind a single Bearer-token-authenticated base URL.

- **Base URL:** `https://api.socialecho.net`
- **Auth:** `Authorization: Bearer sk_live_...`
- **Content-Type:** `application/json`
- **Deployment:** SaaS only (no self-hosted / on-prem option)
- **Machine-readable manifest:** embedded on the marketing page as `<script id="socialecho-agents-manifest" type="application/json">`

---

## Table of Contents

1. [Authentication](#authentication)
2. [Error Format](#error-format)
3. [Publishing Endpoints](#publishing-endpoints)
    - [POST /v1/publish](#post-v1publish)
    - [POST /v1/publish/schedule](#post-v1publishschedule)
    - [GET /v1/publish/:id](#get-v1publishid)
4. [Analytics Endpoints](#analytics-endpoints)
    - [GET /v1/analytics/posts](#get-v1analyticsposts)
    - [GET /v1/analytics/accounts](#get-v1analyticsaccounts)
5. [Monitoring Endpoints](#monitoring-endpoints)
    - [POST /v1/monitors](#post-v1monitors)
    - [GET /v1/monitors/:id/events](#get-v1monitorsidevents)
6. [Agent Framework Integrations](#agent-framework-integrations)
7. [Versioning & Compatibility](#versioning--compatibility)

---

## Authentication

All requests must include a Bearer token in the `Authorization` header. Production tokens start with `sk_live_`; sandbox tokens start with `sk_test_`.

### How to get an API key

The flow is fully self-serve — no sales conversation required:

1. **Pick a paid plan.** Visit the [Pricing page](https://www.socialecho.net/pricing) and subscribe to any tier that fits your usage.
2. **Open the dashboard.** Sign in at <https://app.socialecho.net> and navigate to **System Settings → Team Info → API Key**.
3. **Generate your key.** Click **Generate** to mint a fresh `sk_live_...` token. The full value is shown once — copy it to a secrets manager immediately.
4. **Use it.** Send every request with `Authorization: Bearer sk_live_...`.

```bash
curl -H "Authorization: Bearer sk_live_..." \
     https://api.socialecho.net/v1/publish/job_abc
```

- Tokens are scoped to a single workspace.
- Rotate tokens any time from the same **System Settings → Team Info → API Key** panel.
- Never expose the token to the end user; keep it server-side or inside your agent runtime.

---

## Error Format

Errors use RFC 7807-inspired JSON:

```json
{
  "error": {
    "code": "invalid_account",
    "message": "Account fb_999 is not connected to this workspace",
    "docsUrl": "https://www.socialecho.net/docs/agents.md#error-format",
    "requestId": "req_01HV8..."
  }
}
```

Common codes:

| Code                  | HTTP | Meaning                                          |
| --------------------- | ---- | ------------------------------------------------ |
| `invalid_token`       | 401  | Bearer token missing / malformed                 |
| `forbidden`           | 403  | Token lacks the required scope                   |
| `not_found`           | 404  | Resource does not exist or is not visible        |
| `invalid_account`     | 400  | Referenced social account is not connected       |
| `platform_rejected`   | 502  | Upstream platform (e.g. Facebook) refused the op |
| `internal`            | 500  | SocialEcho internal error — safe to retry        |

---

## Publishing Endpoints

Publishing endpoints push content out to one or more connected social accounts. All publishing jobs are asynchronous: you submit a job and poll its status.

### POST /v1/publish

Publish content immediately to one or more social accounts.

**Request**

```bash
curl -X POST "https://api.socialecho.net/v1/publish" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": ["fb_123", "ig_456"],
    "text": "Hello from my agent!",
    "media": [
      {"type": "image", "url": "https://cdn.example.com/hero.jpg"}
    ]
  }'
```

**Body**

| Field      | Type        | Required | Description                              |
| ---------- | ----------- | -------- | ---------------------------------------- |
| `accounts` | `string[]`  | yes      | One or more connected-account IDs        |
| `text`     | `string`    | yes      | Post body (platform-specific truncation) |
| `media`    | `Media[]`   | no       | Attached images / videos                 |
| `link`     | `string`    | no       | Link to be unfurled                      |

**Response `202 Accepted`**

```json
{ "jobId": "pub_abc", "status": "queued" }
```

### POST /v1/publish/schedule

Schedule a publish job for a future `publishAt` timestamp (UTC, ISO-8601).

**Request**

```bash
curl -X POST "https://api.socialecho.net/v1/publish/schedule" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": ["fb_123"],
    "text": "Scheduled!",
    "publishAt": "2026-05-01T10:00:00Z"
  }'
```

**Response**

```json
{ "jobId": "pub_xyz", "status": "scheduled", "publishAt": "2026-05-01T10:00:00Z" }
```

### GET /v1/publish/:id

Retrieve the status and per-account results of a publish job.

**Request**

```bash
curl "https://api.socialecho.net/v1/publish/pub_abc" \
  -H "Authorization: Bearer sk_live_..."
```

**Response**

```json
{
  "jobId": "pub_abc",
  "status": "completed",
  "createdAt": "2026-04-18T09:00:00Z",
  "completedAt": "2026-04-18T09:00:04Z",
  "results": [
    {
      "account": "fb_123",
      "status": "success",
      "postId": "fb_9876",
      "url": "https://facebook.com/..."
    },
    {
      "account": "ig_456",
      "status": "failed",
      "error": { "code": "platform_rejected", "message": "Media too large" }
    }
  ]
}
```

Job `status` values: `queued`, `scheduled`, `running`, `completed`, `partial`, `failed`.

---

## Analytics Endpoints

Query historical performance data. All analytics endpoints support the `from` / `to` ISO-8601 date parameters and respect workspace timezone.

### GET /v1/analytics/posts

Per-post performance metrics (impressions, engagements, clicks).

**Request**

```bash
curl "https://api.socialecho.net/v1/analytics/posts?from=2026-04-01&to=2026-04-18&account=fb_123" \
  -H "Authorization: Bearer sk_live_..."
```

**Query parameters**

| Parameter | Type     | Description                                   |
| --------- | -------- | --------------------------------------------- |
| `from`    | ISO date | Inclusive start of the range                  |
| `to`      | ISO date | Inclusive end of the range                    |
| `account` | string   | Optional — filter to a single account         |
| `limit`   | integer  | Default 50, max 500                           |

**Response**

```json
{
  "items": [
    {
      "postId": "fb_9876",
      "account": "fb_123",
      "publishedAt": "2026-04-10T12:00:00Z",
      "impressions": 12400,
      "engagements": 532,
      "clicks": 81
    }
  ],
  "pagination": { "next": null }
}
```

### GET /v1/analytics/accounts

Account-level follower and engagement trend series.

**Request**

```bash
curl "https://api.socialecho.net/v1/analytics/accounts?account=fb_123&granularity=day" \
  -H "Authorization: Bearer sk_live_..."
```

**Response**

```json
{
  "account": "fb_123",
  "granularity": "day",
  "series": [
    { "date": "2026-04-17", "followers": 48210, "engagementRate": 0.043 },
    { "date": "2026-04-18", "followers": 48290, "engagementRate": 0.051 }
  ]
}
```

---

## Monitoring Endpoints

Create persistent monitors for keywords or KOL accounts and consume matched events as a stream. Monitors run 24/7 inside SocialEcho infrastructure.

### POST /v1/monitors

Create a monitor.

**Request**

```bash
curl -X POST "https://api.socialecho.net/v1/monitors" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "value": "socialecho",
    "platforms": ["x", "reddit"]
  }'
```

**Body**

| Field       | Type                 | Required | Description                     |
| ----------- | -------------------- | -------- | ------------------------------- |
| `type`      | `keyword` \| `kol`   | yes      | Monitor type                    |
| `value`     | string               | yes      | Keyword or KOL handle           |
| `platforms` | `Platform[]`         | yes      | One or more platform ids        |

**Response**

```json
{ "monitorId": "mon_123", "status": "active" }
```

### GET /v1/monitors/:id/events

Pull the event stream for a monitor. Designed for polling loops in agent runtimes.

**Request**

```bash
curl "https://api.socialecho.net/v1/monitors/mon_123/events?since=2026-04-18T00:00:00Z" \
  -H "Authorization: Bearer sk_live_..."
```

**Response**

```json
{
  "monitorId": "mon_123",
  "events": [
    {
      "id": "evt_1",
      "platform": "x",
      "text": "Love socialecho — agents plug right in.",
      "author": "@user",
      "createdAt": "2026-04-18T03:14:00Z",
      "url": "https://x.com/user/status/..."
    }
  ],
  "cursor": "2026-04-18T03:14:00Z"
}
```

Pass the returned `cursor` as the next request's `since` to avoid duplicates.

---

## Agent Framework Integrations

The API is framework-agnostic, but we publish first-class bindings:

| Framework  | Status          | Link                                                                                           |
| ---------- | --------------- | ---------------------------------------------------------------------------------------------- |
| OpenClaw   | Available       | <https://clawhub.ai/socialecho-net/social-media-autopilot-api> · <https://github.com/SocialEcho-net/social-media-autopilot> |
| Hermes     | Available       | `/product/ai-agents/hermes`                                                                    |
| n8n        | HTTP Node ready | <https://n8n.io>                                                                               |
| Zapier     | Webhook ready   | <https://zapier.com>                                                                           |
| Dify       | OpenAPI ready   | <https://dify.ai>                                                                              |

All frameworks call the same REST endpoints; bindings only add convenience wrappers and error handling.

---

## Versioning & Compatibility

- URL-versioned: `/v1/...`. Breaking changes ship as `/v2`, never as silent `/v1` tweaks.
- Launch-preview tenants keep forward compatibility guarantees through GA.
- Deprecation warnings are returned in the `Sunset` response header (RFC 8594) at least 90 days before removal.

---

_Last updated: 2026-04-18. Questions? Email [api@socialecho.net](mailto:api@socialecho.net)._