API reference
Read-only access to one echooo workspace: KPIs, the post registry, campaigns, boosts and CRM attribution. Every value that echooo doesn't know is null, never 0, and every metric names its source. Writes (approvals, publishing, boosts) stay in the app, where they need a person's consent.
Machine-readable: openapi.json (OpenAPI 3.1). Base URL: https://echooo.work/api/v1
Authentication
An owner or admin creates a key in Settings → API keys, chooses its scopes and expiry, and copies it once. echooo stores only a hash. A key reads one workspace and can't carry access its creator's role doesn't have.
curl https://echooo.work/api/v1/orgs/$WORKSPACE_ID/posts?limit=50 \
-H "Authorization: Bearer $ECHOOO_API_KEY"analytics:read- Analytics KPIs
posts:read- Post registry
campaigns:read- Campaigns
boosts:read- Boosts and spend
attribution:read- CRM attribution
Conventions
- Unknown is null
- A metric echooo doesn't have is
null, never 0, and every metric names its source. - Pagination
- Newest first. Pass
next_cursorback ascursor;limitis 1–100 (default 25). - Rate limit
- 120 requests per minute per key. Responses carry X-RateLimit-* headers; 429 comes with Retry-After.
- Errors
{ "error": { "code", "message", "request_id" } }. Another workspace's id returns 404, not 403.- Read-only
- Approving, publishing and boosting need a person's consent, so they stay in the app.
- Personal data
- Attribution returns HubSpot record ids, not contact names or emails.
Workspace KPIs
GET /orgs/{orgId}/analytics/overview
Scope: analytics:read
Each KPI carries its value, unit, source, coverage, refresh time and definition.
orgId required | string (uuid) Workspace id (Settings → API keys shows it). |
days | integer Period length, 1–730 days. |
key | string |
label | string |
value | number | null Null when unknown. |
unit | count | money_minor | ratio |
currency | string |
period | object |
period.days | integer |
aggregation | string |
source | string |
coverage_ratio | number | null |
last_refreshed_at | string | null (date-time) |
definition | string |
is_estimate | boolean |
Post registry
GET /orgs/{orgId}/posts
Scope: posts:read
Employee posts echooo knows about, with the latest organic impressions (and their source) and tracked-link visits.
orgId required | string (uuid) Workspace id (Settings → API keys shows it). |
limit | integer |
cursor | string Opaque cursor from `next_cursor`. |
status | AWAITING_URL | PUBLISHING | PUBLISHED | FAILED | REMOVED Only posts in this state. |
campaign_id | string (uuid) Only posts linked to this campaign. |
id | string (uuid) |
author | object |
author.employee_id | string (uuid) |
author.name | string |
topic | string | null |
url | string | null (uri) |
status | AWAITING_URL | PUBLISHING | PUBLISHED | FAILED | REMOVED |
method | MANUAL | API | SUBMITTED |
verification | UNVERIFIED | AUTHOR_CONFIRMED_URL | API_CONFIRMED |
published_at | string | null (date-time) |
created_at | string (date-time) |
approved_version_hash | string | null SHA-256 of the exact text the author approved. |
campaign_ids | string (uuid)[] |
metrics | object |
metrics.organic_impressions | object | null |
metrics.organic_impressions.value | integer |
metrics.organic_impressions.source | string |
metrics.organic_impressions.as_of | string (date) |
metrics.tracked_visits | integer | null Null when the post has no tracked link. |
short_url | string | null (uri) |
Campaigns
GET /orgs/{orgId}/campaigns
Scope: campaigns:read
Campaigns with draft and published-post counts.
orgId required | string (uuid) Workspace id (Settings → API keys shows it). |
limit | integer |
cursor | string Opaque cursor from `next_cursor`. |
status | DRAFT | ACTIVE | COMPLETED | ARCHIVED Only campaigns in this state. |
id | string (uuid) |
title | string |
status | DRAFT | ACTIVE | COMPLETED | ARCHIVED |
objectives | string[] |
landing_url | string | null (uri) |
start_date | string | null (date) |
end_date | string | null (date) |
created_at | string (date-time) |
counts | object |
counts.drafts | integer |
counts.published_posts | integer |
Boosts
GET /orgs/{orgId}/boosts
Scope: boosts:read
Boost requests with budget, state and documented results. Ad spend is billed by LinkedIn, not echooo.
orgId required | string (uuid) Workspace id (Settings → API keys shows it). |
limit | integer |
cursor | string Opaque cursor from `next_cursor`. |
state | NOT_ELIGIBLE | ELIGIBLE | AUTHOR_PERMISSION_REQUIRED | AUTHOR_PERMISSION_REQUESTED | AUTHOR_PERMISSION_GRANTED | AUTHOR_PERMISSION_DENIED | CORPORATE_APPROVAL_REQUIRED | READY_TO_SUBMIT | SUBMITTING | ACTIVE | PAUSED | COMPLETED | FAILED | REVOKED | EXTERNAL_HANDOFF_REQUIRED Only boosts in this state. |
id | string (uuid) |
publication_id | string (uuid) |
state | NOT_ELIGIBLE | ELIGIBLE | AUTHOR_PERMISSION_REQUIRED | AUTHOR_PERMISSION_REQUESTED | AUTHOR_PERMISSION_GRANTED | AUTHOR_PERMISSION_DENIED | CORPORATE_APPROVAL_REQUIRED | READY_TO_SUBMIT | SUBMITTING | ACTIVE | PAUSED | COMPLETED | FAILED | REVOKED | EXTERNAL_HANDOFF_REQUIRED |
objective | BRAND_AWARENESS | ENGAGEMENT | WEBSITE_VISITS | VIDEO_VIEWS |
budget | object |
budget.amount_minor | integer |
budget.currency | string |
results | object |
results.spent_minor | integer | null |
results.impressions | integer | null |
results.clicks | integer | null |
results.sources | string[] |
start_date | string (date) |
end_date | string (date) |
external_campaign_id | string | null |
created_at | string (date-time) |
updated_at | string (date-time) |
CRM attribution events
GET /orgs/{orgId}/attribution/events
Scope: attribution:read
HubSpot matches labelled by method. Deterministic: the contact's first or last page seen carried a post's tracked link. Rule-based influence: a time-window rule. Unknown: LinkedIn-sourced without link evidence; never tied to a post.
orgId required | string (uuid) Workspace id (Settings → API keys shows it). |
limit | integer |
cursor | string Opaque cursor from `next_cursor`. |
event_type | VISIT | CONVERSION | NEW_LEAD | DEAL_INFLUENCED Only this event type. |
method | DETERMINISTIC | RULE_BASED_INFLUENCE | UNKNOWN Only this attribution method. |
id | string (uuid) |
occurred_at | string (date-time) |
recorded_at | string (date-time) |
provider | string |
event_type | VISIT | CONVERSION | NEW_LEAD | DEAL_INFLUENCED |
method | DETERMINISTIC | RULE_BASED_INFLUENCE | UNKNOWN |
rule | string | null R1–R5, see the attribution methodology. |
publication_id | string | null (uuid) |
campaign_id | string | null (uuid) |
crm | object HubSpot record ids only; echooo doesn't store contact names or emails. |
crm.contact_id | string | null |
crm.deal_id | string | null |
crm.deal_amount | number | null |
crm.deal_currency | string | null |
Need write access or webhooks? Tell us what you'd build.