Accounts & workspaces

Every request runs inside exactly one workspace. The credential decides which one; there is no account or workspace parameter to pass.

Two products, one API#

Both apps sit on the same data and the same API host, https://api.listener.com. A key minted in either app works against every /v1 endpoint; what it can see depends on the workspace it belongs to.

Workspace kinds#

GET /v1/me reports the kind in kind:

• network: a Listener Networks account with many shows. It owns campaigns, brands, reports, subnetworks and a team.
• subnetwork: a network nested under a parent network (parent_network_uid). It sees its own shows and its own campaigns; the API never crosses into the parent or sibling subnetworks.
• solo: a single show on Listener. Analytics, episodes and clusters work as usual.

The workspace id (effective_uid on GET /v1/me) is the account owner’s id. Show ids, campaign ids and cluster ids are the same ids the apps use, so you can deep-link between your system and the app.

Team members#

When a team member creates a key or authorizes an OAuth app, the credential resolves to the network owner’s workspace, the same workspace the team member sees in the app. Two people on the same team reading /v1/analytics/reach get the same numbers. Usage logs record which credential made each call, so you can still tell them apart.

Network-only resources on solo workspaces#

Some resources only exist for networks: campaigns, subnetworks and the team. On a solo workspace these endpoints succeed with an empty list and a meta.note explaining why, instead of failing. That keeps one code path working for every kind of account:

{
  "object": "list",
  "url": "/v1/campaigns",
  "data": [],
  "has_more": false,
  "next_cursor": null,
  "meta": { "note": "Campaigns are a Listener Networks feature; this workspace is a single show." }
}

Shows that no longer exist#

A network can still point at a show that was deleted. Those ids appear in missing_show_ids on GET /v1/me and are excluded from every list and total, so they never distort a sum.

Plans#

Some features depend on the workspace’s plan. When a plan does not include something, the API answers 403 with plan_required rather than returning partial data. GET /v1/plan tells you what the current plan unlocks.

Public URLs#

Listener pages are shareable, and many objects carry their public URL. The shapes are stable:

GET /v1/urls builds them for you.