Add questions
Submit a batch of 1–50 questions for tracking from the next daily scan.
POST
/api/v1/brands/{brandId}/questionswriteCall the corresponding add_questions MCP tool with JSON arguments. Supply brandId and other path values as named arguments when the endpoint has them.
Request details
Required scope: A valid write token.
Request example
curl --request POST \
--url "https://searchseal.com/api/v1/brands/b7e4c2a0-5d1f-4c8e-9a3b-2f6d8e1c4a70/questions" \
--header "Authorization: Bearer $SEARCHSEAL_TOKEN" \
--header "Content-Type: application/json" \
--data '{"questions":[{"text":"best boutique hotel in ubud","country":"us","topic":"Hotels"},{"text":"quiet villas near ubud rice terraces"}]}'At least one saved question produces 201. If all are skipped without a capacity error, the response is 200.
Items are processed in order using dashboard validation. Reaching capacity skips remaining items with limit_reached; if none were saved, the response is 409 limit_reached.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
brandId | path | Yes | uuid | An active brand ID returned by the brand list. |
questions | body | Yes | object[] | 1–50 { text, country?, topic? } objects. The schema accepts 1–500 text characters, but creation requires 10–150 after trimming. topic allows 50. Country determines language; omitted country defaults to us. |
Response fields
Response body example
{
"items": [
{
"id": "e3a9d1e2-7b4c-4f60-8e2a-9c1d5b7f3e21",
"text": "best boutique hotel in ubud",
"originalText": null,
"country": "us",
"language": "en",
"status": "active",
"createdAt": "2026-09-26T08:15:02.114Z"
}
],
"skipped": [
{
"index": 1,
"code": "duplicate",
"message": "This prompt already exists in United States"
}
],
"meta": {
"generatedAt": "2026-09-26T08:15:02.114Z",
"timeZone": "Asia/Jakarta"
}
}| Field | Type | Description |
|---|---|---|
items | Question[] | Successfully saved questions, preserving submission order. |
skipped | object[] | Rejected items as { index, code, message }, using zero-based indexes. Codes include duplicate, too_short, too_long, invalid_region, localized_unavailable, brand_inactive, limit_reached. |
Successful REST responses from this endpoint include the shown meta fields. Read about data-through dates.
Possible errors
400 invalid_request— An input failed validation. Field details may appear inerrors.401 unauthorized— Authentication failed because the token is absent, unrecognized or revoked.403 forbidden— Account access or token permissions do not allow this request. Check the message for the cause.404 not_found— The resource is missing or unavailable to this account, including inactive brands.409 limit_reached— The account’s active-question capacity is exhausted.429 rate_limited— A quota was reached or could not be checked. Wait theRetry-Afterdelay before retrying.500 server_error— The server failed to complete the operation.
For the shared error format, see status codes, quotas and retries. Next endpoint: Archive question.