Skip to content

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_cursor back as cursor; limit is 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.

Query and path parameters
orgId requiredstring (uuid)
Workspace id (Settings → API keys shows it).
daysinteger
Period length, 1–730 days.
Each item in data
keystring
labelstring
valuenumber | null
Null when unknown.
unitcount | money_minor | ratio
currencystring
periodobject
period.daysinteger
aggregationstring
sourcestring
coverage_rationumber | null
last_refreshed_atstring | null (date-time)
definitionstring
is_estimateboolean

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.

Query and path parameters
orgId requiredstring (uuid)
Workspace id (Settings → API keys shows it).
limitinteger
cursorstring
Opaque cursor from `next_cursor`.
statusAWAITING_URL | PUBLISHING | PUBLISHED | FAILED | REMOVED
Only posts in this state.
campaign_idstring (uuid)
Only posts linked to this campaign.
Each item in data
idstring (uuid)
authorobject
author.employee_idstring (uuid)
author.namestring
topicstring | null
urlstring | null (uri)
statusAWAITING_URL | PUBLISHING | PUBLISHED | FAILED | REMOVED
methodMANUAL | API | SUBMITTED
verificationUNVERIFIED | AUTHOR_CONFIRMED_URL | API_CONFIRMED
published_atstring | null (date-time)
created_atstring (date-time)
approved_version_hashstring | null
SHA-256 of the exact text the author approved.
campaign_idsstring (uuid)[]
metricsobject
metrics.organic_impressionsobject | null
metrics.organic_impressions.valueinteger
metrics.organic_impressions.sourcestring
metrics.organic_impressions.as_ofstring (date)
metrics.tracked_visitsinteger | null
Null when the post has no tracked link.
short_urlstring | null (uri)

Campaigns

GET /orgs/{orgId}/campaigns

Scope: campaigns:read

Campaigns with draft and published-post counts.

Query and path parameters
orgId requiredstring (uuid)
Workspace id (Settings → API keys shows it).
limitinteger
cursorstring
Opaque cursor from `next_cursor`.
statusDRAFT | ACTIVE | COMPLETED | ARCHIVED
Only campaigns in this state.
Each item in data
idstring (uuid)
titlestring
statusDRAFT | ACTIVE | COMPLETED | ARCHIVED
objectivesstring[]
landing_urlstring | null (uri)
start_datestring | null (date)
end_datestring | null (date)
created_atstring (date-time)
countsobject
counts.draftsinteger
counts.published_postsinteger

Boosts

GET /orgs/{orgId}/boosts

Scope: boosts:read

Boost requests with budget, state and documented results. Ad spend is billed by LinkedIn, not echooo.

Query and path parameters
orgId requiredstring (uuid)
Workspace id (Settings → API keys shows it).
limitinteger
cursorstring
Opaque cursor from `next_cursor`.
stateNOT_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.
Each item in data
idstring (uuid)
publication_idstring (uuid)
stateNOT_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
objectiveBRAND_AWARENESS | ENGAGEMENT | WEBSITE_VISITS | VIDEO_VIEWS
budgetobject
budget.amount_minorinteger
budget.currencystring
resultsobject
results.spent_minorinteger | null
results.impressionsinteger | null
results.clicksinteger | null
results.sourcesstring[]
start_datestring (date)
end_datestring (date)
external_campaign_idstring | null
created_atstring (date-time)
updated_atstring (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.

Query and path parameters
orgId requiredstring (uuid)
Workspace id (Settings → API keys shows it).
limitinteger
cursorstring
Opaque cursor from `next_cursor`.
event_typeVISIT | CONVERSION | NEW_LEAD | DEAL_INFLUENCED
Only this event type.
methodDETERMINISTIC | RULE_BASED_INFLUENCE | UNKNOWN
Only this attribution method.
Each item in data
idstring (uuid)
occurred_atstring (date-time)
recorded_atstring (date-time)
providerstring
event_typeVISIT | CONVERSION | NEW_LEAD | DEAL_INFLUENCED
methodDETERMINISTIC | RULE_BASED_INFLUENCE | UNKNOWN
rulestring | null
R1–R5, see the attribution methodology.
publication_idstring | null (uuid)
campaign_idstring | null (uuid)
crmobject
HubSpot record ids only; echooo doesn't store contact names or emails.
crm.contact_idstring | null
crm.deal_idstring | null
crm.deal_amountnumber | null
crm.deal_currencystring | null

Need write access or webhooks? Tell us what you'd build.