Browse all documentation

Add questions

Submit a batch of 1–50 questions for tracking from the next daily scan.

POST/api/v1/brands/{brandId}/questionswrite

Call 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

NameLocationRequiredTypeDescription
brandIdpathYesuuidAn active brand ID returned by the brand list.
questionsbodyYesobject[]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"
  }
}
FieldTypeDescription
itemsQuestion[]Successfully saved questions, preserving submission order.
skippedobject[]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 in errors.
  • 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 the Retry-After delay 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.