API reference
API keys
Manage the keys that authenticate calls to the API: create them, list them, rename and revoke them.
All endpoints need a full-access key whose creator holds the API controls privilege in the console. They can also return the common errors listed in the overview. For choosing permissions and storing keys safely see API keys.
| Endpoint | Node.js | Python | CLI |
|---|---|---|---|
| GET /api-keys | apiKeys.list | api_keys.list | tsmart api-keys list |
| POST /api-keys | apiKeys.create | api_keys.create | tsmart api-keys create |
| PATCH /api-keys/{id} | apiKeys.update | api_keys.update | tsmart api-keys rename |
| DELETE /api-keys/{id} | apiKeys.remove | api_keys.remove | tsmart api-keys delete |
There is no endpoint that returns a single key: a key's secret is shown only once, in the response that creates it.
GET /api-keys
Lists the company's active keys, newest first. Revoked keys and key secrets are never returned.
Permission: full access; the key's creator needs the API controls privilege.
Query
| Name | Type | Description |
|---|---|---|
limit | integer | 1 to 100, default 20. |
after | string | A key id: return older keys. |
before | string | A key id: return newer keys. Use either after or before. |
Request
curl https://send.tsmart.ai/api-keys \
-H "Authorization: Bearer $TSMART_API_KEY"Response
{
"object": "list",
"has_more": false,
"data": [
{
"id": "6d0c9a8e-2f41-4b7a-8e5d-c3b2a1908f7e",
"name": "Production (shop)",
"permission": "sending_access",
"domain_id": "a3b1c5d2-7e8f-4a6b-9c0d-1e2f3a4b5c6d",
"created_at": "2026-10-10 14:02:55.118204+00",
"last_used_at": "2026-10-12 09:15:02.404117+00"
},
{
"id": "0f7e3b21-94c6-4d0a-b5e8-71a2c9d6e403",
"name": "Deploy tooling",
"permission": "full_access",
"domain_id": null,
"created_at": "2026-10-09 08:40:13.552019+00",
"last_used_at": null
}
]
}| Name | Type | Description |
|---|---|---|
id | string | Key id (UUID). This is not the secret. |
name | string | The key's name. |
permission | string | full_access or sending_access. |
domain_id | string | null | For a sending key restricted to one domain, that domain's id; otherwise null. |
created_at | string | When the key was created. |
last_used_at | string | null | When the key was last used (updated at most once a minute); null if never. |
Errors
| Status | Name | When |
|---|---|---|
| 401 | restricted_api_key | A sending-access key. |
| 403 | invalid_permission | The key's creator lacks the API controls privilege. |
| 422 | validation_error | limit out of range, both after and before, or an invalid cursor. |
POST /api-keys
Creates a key and returns its secret, once.
Permission: full access; the key's creator needs the API controls privilege.
Body
| Name | Type | Description |
|---|---|---|
name required | string | A name to recognise the key by, 1 to 50 characters after trimming, without control characters. |
permission | string | full_access (default) or sending_access. |
domain_id | string | Restricts a sending_access key to one domain: the id of one of the company's domains whose ownership is proven. Not allowed with full_access. |
Request
curl -X POST https://send.tsmart.ai/api-keys \
-H "Authorization: Bearer $TSMART_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production (shop)",
"permission": "sending_access",
"domain_id": "a3b1c5d2-7e8f-4a6b-9c0d-1e2f3a4b5c6d"
}'const { data, error } = await tsmart.apiKeys.create({
name: "Production (shop)",
permission: "sending_access",
domain_id: "a3b1c5d2-7e8f-4a6b-9c0d-1e2f3a4b5c6d",
});key = client.api_keys.create({
"name": "Production (shop)",
"permission": "sending_access",
"domain_id": "a3b1c5d2-7e8f-4a6b-9c0d-1e2f3a4b5c6d",
})Response
{
"id": "6d0c9a8e-2f41-4b7a-8e5d-c3b2a1908f7e",
"object": "api_key",
"token": "ts_8Kq2Lm7P_…"
} token is the full key, ts_ followed by an 8-character id, an underscore and a 32-character
secret. Store it right away: it cannot be shown again.
Errors
| Status | Name | When |
|---|---|---|
| 401 | restricted_api_key | A sending-access key. |
| 403 | invalid_permission | The key's creator lacks the API controls privilege. |
| 422 | missing_required_field | name is missing or empty. |
| 422 | validation_error | name is longer than 50 characters or has control characters; permission is not full_access or sending_access; domain_id is given for a full-access key, or is not a domain of the company with proven ownership. |
PATCH /api-keys/{id}
Renames a key. Its secret and permission do not change.
Permission: full access; the key's creator needs the API controls privilege.
Path
| Name | Type | Description |
|---|---|---|
id required | string | The key id (not the secret). |
Body
| Name | Type | Description |
|---|---|---|
name required | string | The new name, 1 to 50 characters after trimming, without control characters. |
Request
curl -X PATCH https://send.tsmart.ai/api-keys/6d0c9a8e-2f41-4b7a-8e5d-c3b2a1908f7e \
-H "Authorization: Bearer $TSMART_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Production (web shop)" }'tsmart api-keys rename 6d0c9a8e-2f41-4b7a-8e5d-c3b2a1908f7e --name "Production (web shop)"Response
{
"object": "api_key",
"id": "6d0c9a8e-2f41-4b7a-8e5d-c3b2a1908f7e"
}Errors
| Status | Name | When |
|---|---|---|
| 401 | restricted_api_key | A sending-access key. |
| 403 | invalid_permission | The key's creator lacks the API controls privilege. |
| 404 | not_found | No active key with this id in your company ("API key not found"). |
| 422 | validation_error | name is missing, empty, longer than 50 characters or has control characters. |
DELETE /api-keys/{id}
Revokes a key at once: every later call with it gets 403 invalid_api_key.
Permission: full access; the key's creator needs the API controls privilege.
Path
| Name | Type | Description |
|---|---|---|
id required | string | The key id (not the secret). |
Request
curl -X DELETE https://send.tsmart.ai/api-keys/6d0c9a8e-2f41-4b7a-8e5d-c3b2a1908f7e \
-H "Authorization: Bearer $TSMART_API_KEY"Response
{
"object": "api_key",
"id": "6d0c9a8e-2f41-4b7a-8e5d-c3b2a1908f7e",
"deleted": true
}Errors
| Status | Name | When |
|---|---|---|
| 401 | restricted_api_key | A sending-access key. |
| 403 | invalid_permission | The key's creator lacks the API controls privilege. |
| 404 | not_found | No active key with this id in your company. |