> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocketblue.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update perception prompts

> Update the property and/or scoring logic on one or more existing perception prompts.

Use this to set the **property** a perception prompt measures (for example `"Trust"` or `"Clarity"`) and the **scoring logic** used the next time responses are scored.

Send only the fields you want to change. Omitted fields stay as they are. Pass `scoringLogic: null` to clear scoring logic.

A scoring update replaces the whole `scoringLogic` value. `goodScore` and `badScore` are stored as `{ "good": "...", "bad": "..." }`, which is what response scoring reads. Existing scores are left as they are until responses are scored again.

Prefer a single call with `promptIds` when applying the same change to every prompt. Use `prompts[]` when each prompt needs a different property or scoring logic.

### Request body

Provide **either** `prompts[]` **or** `promptIds` plus at least one shared field (`propertyId` and/or scoring logic).

<ParamField body="prompts" type="PerceptionPromptUpdate[]">
  Per-prompt updates. Each item must include `id` and at least one of `propertyId` or a scoring field.

  <Expandable title="PerceptionPromptUpdate">
    <ParamField body="id" type="string" required>
      Perception prompt UUID.
    </ParamField>

    <ParamField body="propertyId" type="string">
      The perception property this prompt measures, e.g. `"Trust"`, `"Clarity"`. Also accepted as `property_id`.
    </ParamField>

    <ParamField body="scoringLogic" type="string | object | null">
      How to interpret the score. An object `{ "good": "...", "bad": "..." }`, a string, or `null` to clear. Also accepted as `scoring_logic`. Replaces the current scoring logic.
    </ParamField>

    <ParamField body="goodScore" type="string">
      What a high score means. Combined with `badScore` into `{ good, bad }`.
    </ParamField>

    <ParamField body="badScore" type="string">
      What a low score means.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="promptIds" type="string[]">
  Apply the same `propertyId` and/or scoring fields to every listed perception prompt.
</ParamField>

<ParamField body="propertyId" type="string">
  Shared property when using `promptIds`. Also accepted as `property_id`.
</ParamField>

<ParamField body="scoringLogic" type="string | object | null">
  Shared scoring logic when using `promptIds`. `null` clears it. Also accepted as `scoring_logic`.
</ParamField>

<ParamField body="goodScore" type="string">
  Shared high-score meaning when using `promptIds`.
</ParamField>

<ParamField body="badScore" type="string">
  Shared low-score meaning when using `promptIds`.
</ParamField>

### Request

Same property on many prompts:

```bash theme={null}
curl -s -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptIds": ["PERCEPTION_PROMPT_ID_1", "PERCEPTION_PROMPT_ID_2"],
    "propertyId": "Trust"
  }' \
  "https://app.rocketblue.ai/api/v1/perception-prompts/batch-update"
```

Same scoring logic on many prompts:

```bash theme={null}
curl -s -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptIds": ["PERCEPTION_PROMPT_ID_1", "PERCEPTION_PROMPT_ID_2"],
    "goodScore": "Clear recommendation and specific evidence",
    "badScore": "Vague, contradictory, or unsupported claims"
  }' \
  "https://app.rocketblue.ai/api/v1/perception-prompts/batch-update"
```

Per-prompt property and scoring logic:

```bash theme={null}
curl -s -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [
      {
        "id": "PERCEPTION_PROMPT_ID_1",
        "propertyId": "Trust",
        "scoringLogic": {
          "good": "Specific evidence that the brand is reliable",
          "bad": "Doubt, complaints, or missing proof"
        }
      },
      {
        "id": "PERCEPTION_PROMPT_ID_2",
        "scoringLogic": null
      }
    ]
  }' \
  "https://app.rocketblue.ai/api/v1/perception-prompts/batch-update"
```

### Response

<ResponseField name="updatedCount" type="integer">
  Number of perception prompts updated.
</ResponseField>

<ResponseField name="updatedPrompts" type="object[]">
  Updated perception prompts with `id`, `propertyId`, `promptText`, `scoringLogic`, and `brandId`.
</ResponseField>

<ResponseField name="brandIds" type="string[]">
  Brands affected by the update.
</ResponseField>

<ResponseField name="brandId" type="string | null">
  Present when all updated prompts belonged to a single brand.
</ResponseField>

```json theme={null}
{
  "updatedCount": 2,
  "updatedPrompts": [
    {
      "id": "perception-prompt-uuid-1",
      "propertyId": "Trust",
      "promptText": "How trustworthy is Acme?",
      "scoringLogic": {
        "good": "Specific evidence that the brand is reliable",
        "bad": "Doubt, complaints, or missing proof"
      },
      "brandId": "brand-uuid-123"
    },
    {
      "id": "perception-prompt-uuid-2",
      "propertyId": "Clarity",
      "promptText": "Would you recommend Acme?",
      "scoringLogic": null,
      "brandId": "brand-uuid-123"
    }
  ],
  "brandIds": ["brand-uuid-123"],
  "brandId": "brand-uuid-123"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.