Update prompt

Moves a prompt to a different topic, or sets its funnel stages. Only the fields you send change; pass null to clear one.

Requires the write:prompts scope, and the workspace must be enabled for API writes.


PATCH /v1/brands/{brand_id}/prompts/{prompt_id}

Authorization

Header	Type	Required
`Authorization`	`Bearer asky_sk_…`	required
`Idempotency-Key`	`string`	required

Path parameters

Parameter	Type	Required	Description
`brand_id`	`uuid`	required	From List brands
`prompt_id`	`uuid`	required	From List prompts

Query parameters

None.

Body

application/json. At least one field is required.

Field	Type	Required	Description
`topic_id`	`uuid \| null`	optional	Move the prompt to this topic. `null` leaves it uncategorised. Must be a topic on the same brand
`funnel_stages`	`enum[] \| null`	optional	One to three of `top`, `middle`, `bottom`. Ordered — element 0 is the dominant stage. `null` clears them

Request

cURL


curl --request PATCH \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/3cb1aa79-4310-435a-bd48-1ba26b4724da' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-per-attempt>' \
  --header 'Content-Type: application/json' \
  --data '{"topic_id":"894e113a-4478-49d9-a304-fec21be30cdb","funnel_stages":["bottom","middle"]}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/3cb1aa79-4310-435a-bd48-1ba26b4724da"
headers = {"Authorization": "Bearer <api-key>", "Idempotency-Key": "<unique-per-attempt>"}
payload = {"topic_id": "894e113a-4478-49d9-a304-fec21be30cdb", "funnel_stages": ["bottom", "middle"]}
 
response = requests.patch(url, json=payload, headers=headers)
print(response.text)

JavaScript


const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <api-key>', 'Idempotency-Key': '<unique-per-attempt>', 'Content-Type': 'application/json'},
  body: JSON.stringify({topic_id: '894e113a-4478-49d9-a304-fec21be30cdb', funnel_stages: ['bottom', 'middle']})
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/3cb1aa79-4310-435a-bd48-1ba26b4724da', options)
  .then(res => res.json()).then(res => console.log(res)).catch(err => console.error(err));

Response

200


{
  "data": {
    "prompt": {
      "id": "3cb1aa79-4310-435a-bd48-1ba26b4724da",
      "prompt_text": "How can I optimize a headless CMS to improve visibility in AI-generated answers?",
      "topic_id": "894e113a-4478-49d9-a304-fec21be30cdb",
      "funnel_stages": ["bottom", "middle"],
      "is_active": true
    }
  },
  "request_id": "req_7d21b0af59c34e18b6ac"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "topic_id not found for this brand.",
    "request_id": "req_4c81a0be29d34f1a6b72"
  }
}

404


{
  "error": {
    "code": "not_found",
    "message": "Not found.",
    "request_id": "req_5b0e77d213a94f6a8ce1"
  }
}

403


{
  "error": {
    "code": "insufficient_scope",
    "message": "This action requires the \"write:prompts\" scope, which your token does not have.",
    "request_id": "req_2a71d0ce38f14b9c7d05"
  }
}

Response fields

The prompt after the change, in the same shape List prompts returns its rows, so you can put it straight into a cache.

Field	Type	Description
`data.prompt.id`	`uuid`	required
`data.prompt.prompt_text`	`string`	required. Returned for confirmation; not editable here
`data.prompt.topic_id`	`uuid \| null`	required
`data.prompt.funnel_stages`	`string[]`	required. `[]` when none
`data.prompt.is_active`	`boolean`	required. Always `true` today — see Notes
`request_id`	`string`	required

Errors

Status	Code	When
400	`invalid_request`	Unknown field, a body with neither field, a `topic_id` from another brand, or `funnel_stages` outside one-to-three of the three values
401	`invalid_token`	The key is missing, malformed, or does not exist
403	`insufficient_scope`	The key does not carry `write:prompts`
403	`plan_required`	This workspace is not enabled for API writes
404	`not_found`	The prompt does not exist or belongs to another brand
429	`rate_limited`	Over 60 requests per minute

Notes

funnel_stages is an ordered array, not a set. Element 0 is the dominant stage, and the order is what the product displays. ["middle","bottom"] is not the same as ["bottom","middle"].

An empty array is not a valid way to clear it. The database requires between one and three stages when the column is set, so use null.

Clearing does not schedule reclassification. The automatic classifier only ever considers prompts that have never been classified — it selects on funnel_stages IS NULL and funnel_classified_at IS NULL. A prompt that was classified once keeps that timestamp, so sending null leaves it with no stages and it will not be picked up again. Set the stages you want rather than clearing and waiting.

prompt_text is not editable here. The text is the label on every measurement attached to the prompt, and the app guards edits to it — past 48 hours only small changes are allowed, to keep that history meaningful. Carrying that rule faithfully is its own piece of work.

Tags are set elsewhere. Use Set prompt tags to replace a prompt’s tags, or Bulk add tag to prompts to apply one tag across many.

A prompt cannot be paused. There is no deactivate, archive or disable. is_active exists on the row and is true for every prompt in production; pausing was considered and never shipped. A tracked prompt runs until it is deleted, and deleting it destroys its history.

Creating prompts is not available here. Prompts are plan-limited, so creation spends entitlement rather than editing configuration, and it is quota-checked separately.

Idempotency-Key is required. See Idempotency.