Skip to main content
PUT
Sync prompts

Authorizations

Authorization
string
header
required

A Surfais API key — an organisation key or a partner key. Issued by Surfais; shown once. Rotate by creating a new key, then revoking the old one.

Headers

Idempotency-Key
string

Optional. 1–255 characters, unique per intended write. Same key + same request → the stored response is replayed with Idempotent-Replayed: true; same key + different request → 409 idempotency_key_reuse; still running → 409 idempotency_key_in_flight. Outside that range → 400 validation_error (invalid_header).

Required string length: 1 - 255

Path Parameters

orgId
string<uuid>
required

Organisation id. Org keys: the key's own org. Partner keys: any org with an active link. Anything else is 404.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
brandId
string<uuid>
required

Brand id within the org (own brand or competitor row); 404 when not in the org. Writes that add tracking need an own (400 validation_error with details[].code = "own_brand_only"), non-archived (409 brand_archived) brand.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

application/json
prompts
object[]
required

The desired ACTIVE prompt set for the brand, at most 500 rows. Two rows with the same text (case- and whitespace-insensitive) are 400 duplicate_prompt_text. An empty list with deactivate_missing: true deactivates every active prompt of the brand.

Maximum array length: 500
deactivate_missing
boolean
default:true

Deactivate active prompts of the brand that are not in prompts. Default true.

dry_run
boolean
default:false

Return the plan (results[].action per row) without writing anything.

Response

Multi-status result: what was created / updated / reactivated / unchanged / reasserted / reinstated / deactivated / failed.

data
object
required