Getting started

Quickstart

Create a token, list your accounts, schedule a post. About five minutes, assuming you already have one social account connected.

Before you start

An Echoia workspace with at least one connected social account.
Owner or admin role — members and viewers cannot create tokens.

1. Create a token

In the app, open Settings → Developers and select New token. Give it a name you will recognise in six months (“staging script” beats “test”), then choose its scopes.

For this walkthrough, read and write are enough. Leave publish and engage off — you can create a second token later for anything that acts publicly.

Shown once

The key appears exactly once, at creation. Only its hash is stored, so it cannot be recovered — if you lose it, revoke it and create another. Copy it somewhere safe now.

shell

export ECHOIA_API_KEY="eko_your_key_here"

2. Make your first call

Listing accounts is the cheapest way to check that the token works and to get the ids you will need later.

curl

curl https://app.echoia.io/api/v1/accounts \
  -H "Authorization: Bearer $ECHOIA_API_KEY"

You should get something like this:

response

{
  "accounts": [
    {
      "id": "cmq7f2x8b0001sl3k9a2vd8pq",
      "platform": "instagram",
      "username": "yourbrand",
      "followers": 1842,
      "isActive": true,
      "needsReconnect": false
    }
  ]
}

Empty array?

An empty accounts list means the workspace has no active connection — not that the token is wrong. A wrong token returns 401.

3. Schedule a post

A post without scheduledAt is saved as a draft. Add a future timestamp and Echoia publishes it at that moment — it stays editable in the app until then, which makes it the safe way to test.

curl

curl -X POST https://app.echoia.io/api/v1/posts \
  -H "Authorization: Bearer $ECHOIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Testing the Echoia API.",
    "platforms": ["instagram"],
    "scheduledAt": "2026-12-01T09:00:00Z"
  }'

response

{
  "post": {
    "id": "cmq7f8k1c0003sl3k7b4xe9rt",
    "status": "scheduled",
    "scheduledAt": "2026-12-01T09:00:00.000Z",
    "platforms": ["instagram"]
  },
  "note": "Scheduled. It stays editable in the Echoia Posts tab until publish time."
}

Open the Posts tab in the app and it is there, on the calendar. Delete it from the interface when you are done testing.

The same thing in code

JavaScript

node

const echoia = (path, init = {}) =>
  fetch(`https://app.echoia.io/api/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.ECHOIA_API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  }).then(async (r) => {
    if (!r.ok) throw new Error((await r.json()).error);
    return r.json();
  });

const { accounts } = await echoia("/accounts");
console.log(accounts.map((a) => `${a.platform}: ${a.followers}`));

Python

python

import os, requests

s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['ECHOIA_API_KEY']}"
BASE = "https://app.echoia.io/api/v1"

accounts = s.get(f"{BASE}/accounts").json()["accounts"]
for a in accounts:
    print(a["platform"], a["followers"])

Where to go next

If you want to…	Read
Understand scopes before granting publish or engage	Authentication
Know what happens when you hit a limit	Rate limits & quotas
Publish immediately instead of scheduling	Posts endpoint
Let an AI client drive the workspace	MCP server

Authentication

Scopes, workspace isolation and how tokens are stored.

API reference

Every endpoint, parameter and response shape.

Was this page helpful?