# Trenzhub agent instructions

Use Trenzhub to research search demand, discover trends, manage the user's watchlist, and run Trends Mining.

## Setup

1. The user registers or signs in at https://trenzhub.com/auth/sign-up.
2. The user creates a scoped API key at https://trenzhub.com/settings/api-keys.
3. Store the secret in the local TRENZHUB_API_KEY environment variable or your secret manager. Never commit it, embed it in URLs, or send it to any host other than https://trenzhub.com.
4. Read the API reference at https://trenzhub.com/developers and the machine-readable OpenAPI document at https://trenzhub.com/api/v1/openapi.json.

The current plan is a free trial. No credit card or payment is required. API and MCP share 120 requests/minute and 10000 requests/day per account. Website mining quotas still apply. Daily limits reset at 00:00 UTC.

## REST API

Base URL: https://trenzhub.com/api/v1
Authentication: Authorization: Bearer <TRENZHUB_API_KEY>
Write requests: Content-Type: application/json

```sh
curl --fail-with-body "https://trenzhub.com/api/v1/me" \
  -H "Authorization: Bearer $TRENZHUB_API_KEY"

curl --fail-with-body "https://trenzhub.com/api/v1/keywords/trend?keyword=AI%20agents&locale=en&market=us" \
  -H "Authorization: Bearer $TRENZHUB_API_KEY"
```

Successful JSON responses have { "data": ..., "meta": { "requestId": "...", "apiVersion": "v1", "plan": "free_trial" } }. Errors have { "error": { "code": "...", "message": "..." }, "meta": { "requestId": "..." } }. Export endpoints return downloadable CSV or JSON directly.

## Remote MCP

Endpoint: https://trenzhub.com/mcp
Transport: Streamable HTTP, stateless.
Authentication: the same Authorization: Bearer header, required for every request.
Tools are named trenzhub_<operationId> and use the same parameters, validation, scopes, quotas and ownership checks as REST. tools/list exposes only tools allowed by the key.

Codex configuration (~/.codex/config.toml):

```toml
[mcp_servers.trenzhub]
url = "https://trenzhub.com/mcp"
bearer_token_env_var = "TRENZHUB_API_KEY"
```

Claude Code:

```sh
claude mcp add --transport http trenzhub "https://trenzhub.com/mcp" \
  --header "Authorization: Bearer ${TRENZHUB_API_KEY}"
```

Run that command in a private shell with the environment variable set. Claude Code stores the resolved header in its local MCP configuration; protect that file and never commit it. If a client cannot set HTTP authorization headers, use the REST API instead. This service uses API keys and does not offer an OAuth login flow.

## Available operations

- `get_account`: GET `/me` — Read your profile, current key permissions, and free trial status. Scope: `account:read`.
- `update_account`: PATCH `/me` — Update your display name across your account and active website sessions. Scope: `account:write`.
- `set_avatar`: POST `/me/avatar` — Upload a PNG, JPEG, or WebP avatar as base64 (maximum decoded size 45 KiB). Scope: `account:write`.
- `delete_avatar`: DELETE `/me/avatar` — Remove your profile avatar. Scope: `account:write`.
- `list_sessions`: GET `/me/sessions` — List your active website login sessions. Session tokens are never returned. Scope: `account:read`.
- `revoke_session`: DELETE `/me/sessions/{sessionId}` — Sign out one of your website sessions by its ID. Does not revoke API keys. Scope: `account:security`.
- `revoke_all_sessions`: POST `/me/sessions/revoke-all` — Sign out all of your website login sessions. API keys continue to work. Scope: `account:security`.
- `change_password`: POST `/me/password` — Change your email/password credential using your current password. Revokes website sessions and all other API keys. Scope: `account:security`.
- `list_connections`: GET `/me/connections` — List your linked login providers. Provider secrets and access tokens are never returned. Scope: `account:read`.
- `connect_account`: POST `/me/connections` — Return the account-connections page where the user can complete provider consent in their signed-in browser. Scope: `account:security`.
- `unlink_account`: DELETE `/me/connections/{provider}` — Unlink a Google or GitHub login provider. At least one working login method must remain. Scope: `account:security`.
- `delete_account`: POST `/me/delete` — Permanently delete your account and its owned data. Requires your exact email as confirmation. Admin accounts cannot be deleted. All keys and sessions lose access. Scope: `account:security`.
- `list_markets`: GET `/markets` — List supported languages and markets for keyword targeting. Scope: `trends:read`.
- `get_usage`: GET `/usage` — Read shared API/MCP request usage and your website mining quotas. Quotas reset at midnight UTC. Scope: `account:read`.
- `get_keyword_trend`: GET `/keywords/trend` — Get monthly search history, volume, competition, and bid metrics for a keyword. Scope: `trends:read`.
- `get_keyword_ideas`: GET `/keywords/ideas` — Find related keywords and demand metrics with pagination. Scope: `trends:read`.
- `export_keyword_ideas`: GET `/keywords/ideas/export.csv` — Export one page of related keyword metrics as CSV. Use page and limit to export additional pages. Scope: `trends:read`.
- `list_projects`: GET `/watchlist/projects` — List the projects in your My Trends workspace. Scope: `watchlist:read`.
- `create_project`: POST `/watchlist/projects` — Create a My Trends project, or return an existing project with the same name. Scope: `watchlist:write`.
- `rename_project`: PATCH `/watchlist/projects/{id}` — Rename a project you own. Duplicate project names return a conflict. Scope: `watchlist:write`.
- `delete_project`: DELETE `/watchlist/projects/{id}` — Delete a project you own. Saved keywords remain in My Trends without a project. Scope: `watchlist:write`.
- `list_saved_keywords`: GET `/watchlist/keywords` — List your My Trends keywords, optionally filtered by project, with pagination. Scope: `watchlist:read`.
- `save_keyword`: POST `/watchlist/keywords` — Save a keyword to My Trends, refresh its metrics, and optionally assign it to a project you own. Scope: `watchlist:write`.
- `move_saved_keywords`: POST `/watchlist/keywords/move` — Move up to 50 of your saved keywords to a project, or pass null to remove project assignments. Scope: `watchlist:write`.
- `delete_saved_keywords`: POST `/watchlist/keywords/delete` — Delete up to 50 saved keywords you own. Scope: `watchlist:write`.
- `refresh_saved_keyword`: POST `/watchlist/keywords/{id}/refresh` — Refresh the metrics of one saved keyword. Existing metrics are preserved if the provider fails. Scope: `watchlist:write`.
- `export_watchlist`: GET `/watchlist/export.csv` — Export your saved keyword metrics as CSV, optionally for one project. Scope: `watchlist:read`.
- `list_mining_runs`: GET `/mining/runs` — List your 12 most recent Trends Mining runs for a language and market. Scope: `mining:read`.
- `create_mining_run`: POST `/mining/runs` — Start a background mining run using your existing website quota. Poll get_mining_progress every 5 seconds. Scope: `mining:write`.
- `get_mining_run`: GET `/mining/runs/{runId}` — Read your mining run, candidates, and logs. Only the run owner can access private results. Scope: `mining:read`.
- `get_mining_progress`: GET `/mining/runs/{runId}/progress` — Poll your mining run status and progress. Wait at least 5 seconds between polls. Scope: `mining:read`.
- `stop_mining_run`: POST `/mining/runs/{runId}/stop` — Stop your queued or running mining job and keep its results. Scope: `mining:write`.
- `delete_mining_run`: DELETE `/mining/runs/{runId}` — Delete your mining run, candidates, and logs. Scope: `mining:write`.
- `export_mining_run`: GET `/mining/runs/{runId}/export` — Export your mining results as JSON or CSV. Scope: `mining:read`.
- `list_api_keys`: GET `/keys` — List your key names, prefixes, scopes, expiry, and usage. Secret values are never returned. Scope: `keys:manage`.
- `create_api_key`: POST `/keys` — Create a new key. The secret is returned once. New keys cannot exceed the calling key's scopes or expiry. Scope: `keys:manage`.
- `revoke_api_key`: DELETE `/keys/{keyId}` — Immediately revoke one of your keys. Revoking the current key ends its API and MCP access. Scope: `keys:manage`.

## Workflow

1. Call get_account, get_usage and list_markets before starting research.
2. Use get_keyword_trend and get_keyword_ideas to investigate keywords.
3. Create projects and save or organize keywords in My Trends.
4. Start create_mining_run only when the user wants a new run. Save the returned runId.
5. Poll get_mining_progress no more than once every 5 seconds until completed, failed or stopped.
6. Read get_mining_run or export_mining_run to inspect or export your results.
7. For exports, MCP returns filename, contentType and content; write that content to a local file.

Ask the user before destructive actions unless they already requested them: deleting projects, saved keywords or runs, or revoking keys. Avoid blindly retrying writes; inspect the current state first. A run can be queued even if the initial network response was lost.

## Permissions and errors

Scopes: `account:read`, `account:write`, `account:security`, `trends:read`, `watchlist:read`, `watchlist:write`, `mining:read`, `mining:write`, `keys:manage`.
Use the minimum required scopes. keys:manage and account:security are optional and excluded from the default research key. Child keys cannot outlive or exceed the permissions of their parent key. Revoke each child separately if needed.

401: obtain a valid key. 403: ask the user to grant the needed scope. 404: resource unavailable or owned by another user. 409: inspect resource state. 429: honor Retry-After; check usage and wait for quota reset. 503: retry reads with bounded backoff.

The API exposes registered-user research and account workflows, including avatars, password changes, sessions, and linked providers. Connecting a new OAuth provider requires the user's browser consent; connect_account returns the correct page. Admin controls are not exposed. Appearance and viewed-keyword history are browser-local settings; agents should maintain their own local preferences and history.