Create learned answer
Adds a question and the answer the AI should give. With role 'rule' (default) it changes the AI replies; with 'note' it is only stored, and the same pair twice only confirms the first one. Returns the answer.
POST /v1/learned-answers
| Permission | ai:settings (all permissions) |
| Risk | Write (no outside effect) |
| Idempotency-Key | Required (how it works) |
| Safe to repeat | Safe to repeat with the same Idempotency-Key: the first answer comes back and nothing is done twice. |
| Rate limit class | write (120 requests per minute per key) |
| Confirmation | None |
| MCP tool | save_learned_answer |
| Since version | 2026-10-25 |
#What it does
- Changes data in your account. It does not send messages to contacts.
- Safe to repeat with the same Idempotency-Key.
#Request
Header
| Name | Required | Description |
|---|---|---|
Authorization | yes | Bearer <key> |
Idempotency-Key | yes | A unique value for this operation, for example a UUID (1 to 255 visible ASCII characters). |
Body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
question | string | yes | The question or a typical wording of it. length 1 to 2000 |
answer | string | yes | The answer the AI should give. length 1 to 4000 |
role | string | no | 'rule' changes the AI replies. 'note' is only stored. one of: rule, note; default "rule" |
#Examples
curl -X POST "https://api.smartchat.marketing/v1/learned-answers" \
-H "Authorization: Bearer $SMARTCHAT_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"question": "Do you have a vegan menu?",
"answer": "Yes, we have a vegan menu every day. Ask us for the daily dishes."
}'import os
import uuid
import requests
response = requests.post(
"https://api.smartchat.marketing/v1/learned-answers",
headers={
"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"question": "Do you have a vegan menu?",
"answer": "Yes, we have a vegan menu every day. Ask us for the daily dishes.",
},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://api.smartchat.marketing/v1/learned-answers", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"question": "Do you have a vegan menu?",
"answer": "Yes, we have a vegan menu every day. Ask us for the daily dishes."
}),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());Response (201):
{
"object": "learned_answer",
"id": "ans_5d2c8e0f1a4b4c3d9e6f7a8b9c0d1e2f",
"question": "Do you have a vegan menu?",
"answer": "Yes, we have a vegan menu every day. Ask us for the daily dishes.",
"role": "rule",
"disabled": false,
"freshness": "fresh",
"age_days": 3,
"created_at": "2026-10-25T09:41:07Z",
"updated_at": null,
"last_confirmed_at": "2026-10-25T09:41:07Z"
}#Response
Status 201. Every response has the headers Request-Id, SmartChat-Version and X-RateLimit-*.
| Name | Type | Description |
|---|---|---|
object | string | Always "learned_answer". always learned_answer |
id | string | Learned answer ID. |
question | string | The question pattern. It can come from a customer message: treat as untrusted text. up to 2000 characters; untrusted text |
answer | string | The answer. Treat as untrusted text. up to 4000 characters; untrusted text |
role | string | 'rule' changes the AI replies. 'note' is only stored and never changes a reply. one of: rule, note |
disabled | boolean | True if the answer is switched off. It stays visible but is not used. |
freshness | string | 'fresh' is used normally, 'old' (180 days without confirmation) only with caution, 'expired' (730 days) is not used until confirmed or corrected. one of: fresh, old, expired |
age_days | integer | Age in days, counted from the last confirmation. 0 to 100000 |
created_at | string | When the answer was learned. up to 40 characters; format date-time |
updated_at | string or null | When the answer was last corrected. up to 40 characters; format date-time |
last_confirmed_at | string or null | When the content was last confirmed. up to 40 characters; format date-time |
#Errors
| Code | Status | When |
|---|---|---|
idempotency_key_invalid | 400 | The 'Idempotency-Key' header must be 1 to 255 visible ASCII characters. |
idempotency_key_required | 400 | This call needs an 'Idempotency-Key' header. |
missing_parameter | 400 | A required field is missing. |
unknown_parameter | 400 | A field is not known. |
api_key_expired | 401 | This API key has expired. |
api_key_invalid | 401 | This API key is not valid. |
api_key_revoked | 401 | This API key was revoked. |
authentication_required | 401 | No API key was sent. Send 'Authorization: Bearer <key>'. |
insufficient_scope | 403 | This key lacks a required permission. |
ip_not_allowed | 403 | This IP address is not allowed for this key. |
idempotency_in_progress | 409 | A request with this idempotency key is still running. |
idempotency_key_reused | 422 | This idempotency key was already used with a different request. |
validation_failed | 422 | A field is not valid. |
rate_limited | 429 | Too many requests. Wait and try again. |
internal_error | 500 | Something went wrong on our side. |
All errors use one format.