Developer API

Who can use it

API access is included with the Growth plan and above. Keys are created in the Growth Hub under API & agents; each key authenticates as you and can only do what your account can do in the Growth Hub itself.

Monthly call quotas follow the plan (Growth 10,000, Pro 100,000, Enterprise unlimited) and every key is limited per minute. See pricing.

Authentication

Send your key as a bearer token. Keys start with tlk_live_, are shown once when created, and can be revoked at any time.

curl https://backend.trustlist.uk/api/users/my/dashboard \
  -H "Authorization: Bearer tlk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Scopes

Each key carries the scopes you choose. A call needs the matching scope, and your plan level must include it.

Endpoints

The API is the same set of owner-scoped endpoints the Growth Hub uses, so anything you can do there you can automate. Base URL: https://backend.trustlist.uk.

Publishing an article

# 1. create a draft
curl -X POST https://backend.trustlist.uk/api/users/my/add/article \
  -H "Authorization: Bearer $TRUSTLIST_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"How we cut onboarding time in half","type_listing":"blog",
       "contents":{"long_desc":"# How we cut onboarding time in half\n\n## Why it mattered ..."}}'

# 2. publish it (fails with 422 and the counts if the body is under the minimums)
curl -X PUT https://backend.trustlist.uk/api/users/my/update/article/<id> \
  -H "Authorization: Bearer $TRUSTLIST_API_KEY" -H "Content-Type: application/json" \
  -d '{"publish":{"is_published":true}}'

The same rules as the Growth Hub

Automation doesn't bypass the listing guidelines. Articles publish only with at least 2,000 words, 1 main heading and 4section headings; staff-managed listing types can't be selected; plan slot caps still apply. These checks run on the server for every write, whichever client made it.

Companies and products have their own bar, and it applies at publish — never to a draft. A listing goes live only with a description of at least 120 characters, at least 1 category, and a working http(s) website. Publishing without them returns 400 with a machine-readable body naming exactly what is missing, so an agent can fix and retry without guessing:

{
  "error": {
    "status": 400,
    "message": "This listing is not ready to publish: the description is 18 characters and needs at least 120. pick at least 1 category so buyers can find it.",
    "details": {
      "missing": ["description", "categories"],
      "descriptionChars": 18,
      "minDescriptionChars": 120,
      "categories": 0,
      "minCategories": 1,
      "website": "https://example-vendor.co.uk"
    }
  }
}

There is also a ceiling: a listing may carry at most 20 categories, and unlike the checks above this one applies to every write, not just publishing — a PUT that would leave the listing above the cap is refused with 400 and { "categories": 47, "maxCategories": 20 }. Attaching every category and every town does not widen reach; it dilutes the category pages other businesses earned their place on, and listings already stuffed beyond the cap are trimmed back.

Write the listing properly the first time rather than publishing a stub and filling it in later: a thin page earns nothing, and listings whose website stops resolving are eventually marked closed. If you are generating listings from your own data, populate the description, categories and website in the same call that creates them.

Errors and limits

AI agents and Claude

Because the API is plain HTTPS with a bearer key, any agent framework that can make web requests can use it today: give the agent your key as a secret and this page as its reference. Keep the key scoped to what the agent needs (for example listings:read and listings:write for a content agent), set an expiry, and revoke it when the job is done.

For Claude Desktop, Claude Code and other MCP-aware assistants there is an MCP server that wraps these endpoints as tools (list and edit listings, check an article against the publishing minimums before publishing, read and answer leads, check placement availability). It lives in the TrustList repository under packages/mcp-server and runs locally with your key:

{ "mcpServers": { "trustlist": {
    "command": "node",
    "args": ["/path/to/TrustList/packages/mcp-server/src/index.js"],
    "env": { "TRUSTLIST_API_KEY": "tlk_live_..." } } } }

The server holds no privilege beyond the key you give it, so revoking the key cuts the assistant off instantly.

Questions or a use case we don't cover yet? Contact us.