distribute.you API Reference

Agent quickstart

Base URL

https://api.distribute.you/v1

Auth

Authorization: Bearer distrib.usr_YOUR_KEY on every REST and MCP call. The X-API-Key header is NOT accepted for user keys: it answers 401.

First call

GET /v1/me (or the distribute_status MCP tool). It needs no brand or organization named, and lists every organization the key can act in, each with its brands. Tell the human which organizations and brands you see before anything else.

Scope

One key is one user, across every organization that user belongs to. Membership is checked on each call, so leaving an organization removes it from the key. A key never belongs to a brand, and it carries no staff powers.

Name a brand on each call

Each call acts in ONE organization. Name a brand: ?brandId=, the x-brand-id header, brandId (or brandIds) in a JSON body, or /v1/brands/{id} in the path. When a brand sits in several of your organizations, add ?orgId= (or the x-org-id header). Calls about no brand name the organization with orgId. A user in exactly one organization can name nothing. Routes keyed only by a campaign id need brandId or orgId too when the user is in several organizations.

Targeting errors

Every refusal carries code, message and fix. 400 org_target_required: you named nothing and belong to several organizations; pick one from the organizations list in the body (or from GET /v1/me) and send its brandId or orgId. 400 brand_in_several_orgs: add orgId. 400 brands_span_orgs: the brands are in different organizations; make one call per organization. 403 org_not_member: that organization is not one of yours; use an id from GET /v1/me. 403 no_organization: the user belongs to no organization; ask the human to create or join one in the dashboard. 404 org_not_found or brand_not_found: the id is wrong; read GET /v1/me again. 503 membership_unavailable: retry, keep the same key.

Key refused

A 401 means the key was mistyped, revoked or not sent. Show the human the error as served and ask for a new key from https://dashboard.distribute.you/api-keys. Keys start with distrib.usr_.

Dashboard

https://dashboard.distribute.you (API keys sit in the account menu, under API Keys).

MCP server

https://mcp.distribute.you/mcp, exactly 6 tools: distribute_status, distribute_list_brands, distribute_suggest_icp, distribute_list_campaigns, distribute_campaign_stats, distribute_list_workflows. Everything else goes through the REST API.

How to report results to a human

Lead with what the customer pays for: meetings booked and positive replies, then money earned or return when the API serves it, then the delivery rate ("98% delivered", not "531 sent, 518 delivered"). Volume sent and cost come next. Failures such as bounces and errors go last, in a details line. Never hide a number: 0 positive replies is said plainly.