# TopicalBoost API

> TopicalBoost is a developer API for analyzing website content, assigning entity topics to posts, generating Article JSON-LD, fetching SEO demand metrics, and generating SEO/social meta titles and descriptions.

Use this file as the entry point for LLMs and coding agents. The full integration guide is the source of truth for client behavior; the OpenAPI document is the source of truth for request and response schemas.

Critical integration rules:
- Send request bodies as JSON with `Content-Type: application/json`.
- Send the API key as `x-api-key` on every authenticated request.
- For server-side/non-WordPress clients, send `x-tb-site-url` or `x-tb-site-domain` on authenticated requests when the site domain is known.
- Validate setup with `POST /validate-api-key`. If you send `site_url` and receive `domain_mismatch: true`, surface that to the user before analysis and point the site owner to the customer dashboard/support.
- Use `postId` as the canonical content identifier. Legacy aliases `customer_id` and `customerId` may still appear for compatibility.
- Use `tier` as the canonical ranking and JSON-LD placement signal. Do not use `salience` for new ranking logic.
- Valid tiers are `mainEntity`, `about`, and `mentions`. Treat `null` tier values as `mentions`.
- For single-post results, call `GET /result/entities`. It can include prebuilt JSON-LD entity `schema` objects when `include_schema=true`.
- For bulk results, call `GET /v2/result/posts`. It returns posts with per-post entity tiers, but it does not include prebuilt `schema` objects.
- Do not use `GET /result/customerIds` or `GET /result/customer_ids` for new bulk integrations. They are legacy compatibility endpoints only.
- For bulk JSON-LD, use `posts[].entities[].tier` for the current post. Do not use the shared entity `Contents[]` list to assign one global tier to an entity.
- Demand metrics may be missing from result payloads. Fetch them on demand with `GET /demand/entity/{id}` when needed.
- Use `GET /lookup?q={query}` when an admin or editor needs to search for an entity that automatic analysis missed.
- Use `POST /analyze/bulk/cancel` only when a user aborts an in-progress bulk request.
- The WordPress plugin also calls operational endpoints such as `/content/url`, `/poll/active-request`, `/result/hidden-entities`, `/sync/*`, and `/telemetry/*`. These are plugin state, sync, and telemetry helpers, not the standard custom-client flow.

Recommended workflow:
- Validate connection with `POST /validate-api-key`.
- Analyze one post with `POST /analyze/single`, poll `GET /poll/analysis`, then fetch `GET /result/entities`.
- Analyze many posts with `POST /analyze/bulk/initiate`, send pages with `POST /analyze/bulk/send`, poll `GET /poll/analysis`, then fetch `GET /v2/result/posts`.
- Cancel an abandoned bulk request with `POST /analyze/bulk/cancel`.
- Render JSON-LD by placing entities into `mainEntity`, `about`, and `mentions` according to each entity's tier.
- Generate meta with `POST /meta/generate`, `POST /meta/generate-social`, and `GET/PUT /meta/settings`; generation bodies require `postTitle` and `content` (`contentPreview` is a deprecated alias).
- Fetch demand metrics with `GET /demand/entity/{id}` for analyzed entities or `GET /demand/keyword/{keyword}` for arbitrary keyword strings.
- Search entities with `GET /lookup?q={query}` for manual topic attach or editor tools.

## Primary Documentation

- [Full LLM integration guide](https://api.topicalboost.com/docs/llm-integration-guide.txt): End-to-end instructions for validating a connection, analyzing single and bulk content, polling, reading results, rendering JSON-LD, generating meta, fetching demand metrics, and handling retries.
- [OpenAPI specification](https://api.topicalboost.com/docs/swagger.json): Machine-readable request and response schemas, including optional endpoints such as bulk cancellation and entity lookup.
- [Interactive API docs](https://api.topicalboost.com/docs): Human-readable API reference with examples.
- [Customer dashboard](https://api.topicalboost.com/dashboard): Authenticated customer resources, API quickstart, plugin downloads, changelog notes, and support contact.

## Reference Clients

- [WordPress plugin latest zip](https://api.topicalboost.com/wp-plugin/latest): Canonical production client. The API gateway class shows the request sequence.
- [Drupal Composer package](https://packagist.org/packages/tallesttree/topicalboost-drupal): Companion PHP/Composer reference and Drupal module package. Install with `composer require tallesttree/topicalboost-drupal`.

## Optional

- [TopicalBoost website](https://www.topicalboost.com): Product overview.