#Clickmax API

The Clickmax public API answers at https://mcp.clickmax.io/api/v0. Each request acts on one workspace and is authenticated with that workspace's API key.

#Client libraries

For JavaScript and TypeScript, use the @clickmax/public-sdk package. It has a typed method for every endpoint and returns errors in the format described under Errors. From other languages, call the API over HTTP, as in the cURL example.

Both examples below send the same request: they list the workspace tags.

npm install @clickmax/public-sdk

import { Clickmax } from '@clickmax/public-sdk'

const clickmax = new Clickmax(process.env.CLICKMAX_API_KEY!)

const result = await clickmax.tags.list()

if (result.ok) {
  console.log(result.value.data)
} else {
  const { type, code, requestId } = result.error
  console.error('tags.list failed', { type, code, requestId })
}

curl https://mcp.clickmax.io/api/v0/tags/list \
  -H "Authorization: Bearer $CLICKMAX_API_KEY"

Installation, options, and error handling for the package are covered in How to use the Clickmax TypeScript SDK.

#Authentication

Workspace owners and admins create and revoke keys under Settings > Connections > API. Each workspace can keep up to 5 keys. If you cannot find the screen, ask Max where to create an API key: its button opens that tab directly.

The key is displayed only after creation and cannot be viewed again. To replace a key or change its allowed IP addresses, revoke it and create another one.

The prefix identifies the environment: cxp_ for production, cxs_ for staging, and cxd_ for development.

A key without allowed IP addresses works from any IP. When the list is populated, the API accepts only the exact IPv4 or IPv6 addresses provided.

Send the key with every request:

Authorization: Bearer <api-key>

The key acts on behalf of the whole workspace. Keep it on a server, in an environment variable or a secret manager, and never include it in code that runs in a browser or a mobile app.

A missing or revoked key, a key from another environment, and a key used from an IP outside its list all get the same 401 response with code unauthorized. The response does not say which of these conditions failed.

API keys do not authenticate MCP connections. MCP continues to use OAuth.

#Errors

When a request fails, the API responds with a 4xx or 5xx status and a JSON body like this one:

{
  "error": "Rate limit exceeded.",
  "type": "rate_limit",
  "code": "rate_limit_exceeded",
  "requestId": "8f1c2a3b4c5d6e7f-GRU"
}

Decide how to handle an error by its type, and use the code for specific cases. If you receive a type that is not listed here, handle it by its HTTP status.

These are the most common code values:

Other endpoints can return their own codes, always in lowercase with underscores.

#Request limit

The public API accepts up to 100 requests every 10 seconds per workspace. All API keys in the workspace share this limit.

Above that, the API responds 429 with type rate_limit, code rate_limit_exceeded, and the Retry-After: 10 header, which is the number of seconds to wait before the next attempt. If the error keeps happening, reduce concurrent requests.

#Other resources