Skip to main content
PATCH
Update a prompt

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)$
promptId
string<uuid>
required

Prompt id within the org; 404 when not in the org.

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
countries
string[]

Markets the prompt runs in. Duplicates are collapsed.

Required array length: 1 - 29 elements

ISO 3166-1 alpha-2 market (case-insensitive). Must be one Surfais scans; otherwise 400 validation_error with details[].code = "unsupported_country".

Pattern: ^[A-Za-z]{2}$
platforms
enum<string>[]

Platforms the prompt runs on. Duplicates are collapsed.

Required array length: 1 - 5 elements

Scanned AI platform id.

Available options:
perplexity,
chatgpt,
gemini,
claude,
ai_overviews
tags
string[]

Free-text labels, each at most 100 characters and 256 UTF-8 bytes after trimming, with no control characters. Duplicates are collapsed.

Maximum array length: 50
Required string length: 1 - 100
active
boolean

true on an inactive prompt REACTIVATES it (cap-checked: 422 prompt_cap_exceeded / country_cap_exceeded, 409 conflict if an active prompt with the same text exists in the brand); false deactivates. On a prompt of an archived brand false is accepted only as the SOLE field of the body — sent with any other field the whole patch is 409 brand_archived.

Response

The updated prompt.

data
object
required