Docs
The concepts, the money rules, the connector tools and the REST API, in short.
Free PR writing skill
A skill for Claude that writes press releases and sponsored articles written to pass our checks, then checks and orders them through the connector. How to get and install it.
Buzz Dealer AI agent skill
A skill for Claude, OpenClaw and Hermes that teaches your agent to connect, follow the order flow and ask you before it spends. How to get and install it.
Connect guides for every AI client: Connect.
Concepts
- Account
- The paying customer, with an owner, members, brands and a credits balance.
- Brand
- A company or person you publish for. A brand must be verified before it can be ordered for.
- Credits
- Prepaid balance in US dollars, 1 credit = $1. Unused credits roll over, with no cap.
- Budget frame
- Set by a person, per account and optionally per brand: monthly budget, limit per order, approval threshold, goals, blocked outlets, and approval mode.
- Agent connection
- An MCP connection (OAuth) or an API key, tied to one account and optionally limited to brands. Revocable in the dashboard.
- Catalog item
- A PR distribution package, an individual site (press release article or sponsored article), a bundle, a monthly program, or a service.
- Quote
- The price of the items you ask for, locked for a set time. A quote moves no credits.
- Order and order item
- An order holds one item per unit of work. Each item has its own status, from reserved to published, delayed, failed or refunded.
- Replacement
- When an item fails, we propose an equivalent at an equal or lower price. You accept it, or the credits go back to your balance.
- Approval
- An order outside the frame waits for a person to approve or decline it, in the dashboard or from an email link.
Money rules
- An agent never makes a payment. It only allocates credits a person has already funded.
- Every order is quoted before any credits move.
- On order, credits are reserved. On publication, they are spent per item. On failure, they go back to the balance automatically.
- An order inside the frame goes ahead with no human step. Outside the frame it waits for approval, and the person is emailed.
- If the balance is too low, the order is not placed and the agent is told why.
Connector tools
The tools, with what each does and whether it is read only or spends credits, are on the tools page. Connection steps are on Connect.
REST API
Base URL https://api.buzzdealer.ai. Every request needs an API key as a bearer token. Rate limits per key: 60 read requests and 10 ordering requests per minute; over a limit the answer is 429 with a retry-after header. Status changes can be pushed to you by signed webhooks (set them up in the dashboard under Webhooks). The full specification is at /openapi.json (OpenAPI 3.1).
| Method | Path | What it does | Same as tool |
|---|---|---|---|
| GET | /v1/account | Balance, budget frame, pending approvals and what the monthly plan still includes this month (read only) | get_account_status |
| GET | /v1/publications | Search published catalog items | find_publications |
| GET | /v1/publications/{item_id} | One published item with its required inputs | get_publication |
| POST | /v1/quotes | Price items and lock the quote (moves no credits) | quote_order |
| GET | /v1/orders | The 10 most recent orders | get_order_status |
| POST | /v1/orders | Place an order from a quote (reserves credits). Takes an Idempotency-Key header. | place_order |
| GET | /v1/orders/{order_id} | One order: items, links, delays, replacement offers | get_order_status |
| POST | /v1/replacements/{offer_id} | Accept a replacement, or take the credits back to the balance | respond_to_replacement |
| POST | /v1/campaign-plans | A deterministic campaign plan (read only) | plan_campaign |
| POST | /v1/checks | Originality, content rules and fit check of a text (free up to a monthly limit) | check_originality_and_fit |
| POST | /v1/reports | Report for one order, or one brand over a date range | get_report |
| POST | /v1/ai-visibility-scores | AI score (beta) and tier for catalog outlets by domain | get_ai_visibility_score |
| POST | /v1/audits | Order one audit for a brand or person of the account: brand audit, personal audit, Wikipedia notability check, website analysis, Brand ORM status report or Personal ORM status report (reserves credits) | order_audit |
Errors
Every error is JSON with three fields. next_step tells the agent exactly what to do.
{
"error": "insufficient_credits",
"message": "A short explanation.",
"next_step": "What to do next."
}