Mention Clock REST API
The REST API lists projects, creates a project from a hostname, reads one project, reads the last 50 stored checks, runs a check now, and deletes a project. JSON is sent over HTTPS. A separate unauthenticated route runs one free check. The pricing table links here from the REST API row. Creating a key and calling /api/v1 is available on every plan. Signed webhooks follow the same plan split as Slack or Teams: off on Free, on for Starter, Pro and Agency.
Built by StyleLine FZE in Sharjah. Email support@mentionclock.com. We reply within one business day.
Authentication
Create a key in Settings. An account can hold up to 10 keys. The full key is shown once. The server stores only a SHA-256 hash. The key starts with mcl_. Send it on every /api/v1 request:
curl -H "Authorization: Bearer mcl_..." https://www.mentionclock.com/api/v1/monitors
A missing bearer token, a key that does not start with mcl_, or a hash the account does not recognise returns 401 with {"error":"unauthorized"}. The message is Send Authorization: Bearer <api key>. or Unknown or revoked API key. Revoke a key in Settings at any time. The key acts on the team owner of the account that created it. Responses under /api/v1 send Cache-Control: no-store.
Rate limits
Each key may make 60 requests per minute on /api/v1. The window is 60 seconds from the first request in the bucket. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. X-RateLimit-Reset is the unix second when the bucket resets. Over the limit the route returns 429 with Retry-After and {"error":"rate_limited","message":"Limit is 60 requests per minute per key."}. The free check route has a separate limit, described below.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /api/v1/monitors | List projects and the account limits. |
| POST | /api/v1/monitors | Add a hostname. Returns 201, 400, 402, or 409. |
| GET | /api/v1/monitors/{id} | One project, or 404. |
| GET | /api/v1/monitors/{id}/checks | The last 50 stored checks, or 404. |
| POST | /api/v1/monitors/{id}/check | Run the saved project now and return the project. |
| DELETE | /api/v1/monitors/{id} | Remove a project. Returns 204, or 404. |
| POST | /api/visibility | Anonymous free check. No API key. |
Project object
GET one project and the rows inside GET list use the same object. Fields are id, hostname, port, paused, status, error_code, days_remaining, valid_from, valid_to, issuer, subject, chain_valid, hostname_match, last_checked_at, domain, domain_expires_at and created_at. status is pending before the first check, problem when the last check stored an error code, and ok otherwise. paused follows the plan pause set on the list. GET one project and POST check return paused: false. days_remaining holds the latest share of mentions from 0 to 100. chain_valid and hostname_match are booleans or null.
GET /api/v1/monitors
Returns data, plan, limit, planLimit and bonusLimit. data is the project array. plan is the account plan. limit is the monitor cap after bonuses. planLimit is the plan total. bonusLimit is the bonus portion of that cap.
POST /api/v1/monitors
The body is JSON with hostname and an optional port. A body that is not JSON returns 400 with {"error":"invalid_json"}. A hostname the parser rejects returns 400 with {"error":"invalid_hostname","message":"Send {\"hostname\": \"example.com\"}, optionally with \"port\"."}. The stored port defaults to 443. Success is 201 and {"data": project}. A duplicate hostname and port returns 409 with {"error":"duplicate","message":"That hostname and port are already on the account."}. Over the monitor cap the response is 402 with {"error":"plan_limit","message":"The <plan> plan covers <n> monitors."} using the account plan and the current cap. This route does not accept brand, prompts, rivals, or a category. Those live on the saved project. When a later check runs a row that has no saved project, the brand falls back to the hostname and the website falls back to https:// plus that hostname.
GET /api/v1/monitors/{id}
Returns {"data": project} for a project on the account. A missing id returns 404 with {"error":"not_found"}.
GET /api/v1/monitors/{id}/checks
Returns the last 50 stored checks as {"data":[...]}. Each check has checked_at, ok (boolean), error_code, days_remaining, issuer and valid_to. days_remaining is the share stored for that run. A missing project returns 404 with {"error":"not_found"}. There is no query parameter for a different page size.
POST /api/v1/monitors/{id}/check
No body is read. The route runs the saved project for that id and then returns {"data": project} from the row after the run. A missing id returns 404 with {"error":"not_found"}. When the account has hit its monthly run cap, the check stores an empty capped run and does not call the assistants. Otherwise it runs the prompts on the saved project, stores the run, and sends an alert when the run produces one. The HTTP body of this route is the project object, not the full run.
DELETE /api/v1/monitors/{id}
Returns 204 with an empty body when the project belonged to the account, and 404 with {"error":"not_found"} when it did not.
POST /api/visibility
This route does not use an API key. It is limited to 3 requests per IP address per 24 hours. Over that limit it returns 429 with {"error":"Too many free checks. Try again tomorrow."} and Cache-Control: no-store. The JSON body accepts brand (required, 1 to 80 characters), optional website (1 to 300 characters), optional hostname (1 to 300 characters), optional category (1 to 80 characters), optional competitor (up to 80 characters) and optional kind of visibility or description. A body that fails that shape returns 400 with {"error":"Enter a brand name, website and category."}. Success is 200. The JSON is the run object with resultId added when a public result was saved. A failed run returns 500 with {"error":"..."}. The route applies a cost cap of 0.5 US dollars on that check.
Errors
JSON errors use an error field and a message when the handler sets one. Codes on /api/v1 are unauthorized (401), invalid_json (400), invalid_hostname (400), plan_limit (402), duplicate (409), not_found (404) and rate_limited (429). The free check uses the plain error strings above instead of those codes.
A short script
Create the key in Settings, then GET https://www.mentionclock.com/api/v1/monitors and read plan, limit and data. POST a hostname when the list should gain a row. On 201 or 409, continue. On 402, stop because the plan cap is full. On 401, create a new key. On 429, wait for Retry-After and send that request again. GET /api/v1/monitors/{id}/checks for the last 50 shares. POST /api/v1/monitors/{id}/check when the script should run the saved project now. DELETE only an id you mean to remove. Use POST https://www.mentionclock.com/api/visibility only for an anonymous check, and expect the daily IP cap of 3.
Signed webhooks
Alerts are separate from the REST routes. On a paid plan, when the account has a webhook URL and a signing secret, an alert POSTs JSON. The event header is X-MentionClock-Event. The value is mention.dropout, mention.competitor, mention.share, mention.source, mention.accuracy, or mention.change when the alert kind is none of those five. The signature header is X-MentionClock-Signature: t=<unix seconds>,v1=<hex>. v1 is HMAC-SHA256 of the unix timestamp, a dot, and the raw body, using the signing secret. The sender does not attach an expiry of its own. Compare t with your clock when you verify the signature. Free accounts do not receive webhook posts.
Choosing a tool is a different job from a single method. The dated vendor scorecard is best ChatGPT brand monitoring tools.