---
title: "Update Prism"
method: PUT
path: "/api/v1/admin/prisms/{prism_id}"
tags: ["Admin APIs", "prisms"]
---

# Update Prism

`PUT /api/v1/admin/prisms/{prism_id}`

Update a prism. Live saves recompute only under the 5:00 PM ET / freshness
rules (see ``_should_recompute_on_live_save``); copy-only skips re-compose
the cached tile (display fields come from the definition, not the compute).
Unpublishing drops the tile from the serving cache.

Going live always requires a successful recompute. If refresh fails on a
draft→live transition, ``publish_state`` is rolled back to draft — a
prism never sits live without a computed snapshot. Other field edits from
the same request are kept. Already-live edits that fail recompute keep
live + last-good tile; the structured error says so.

## Path parameters

- `prism_id` string, required

## Request body

- PrismDefinitionUpdate
  - `title` string, nullable
  - `category_id` string, uuid, nullable
  - `question` string, nullable
  - `question_share` string, nullable
  - `note` string, nullable
  - `insight_id` integer, nullable
  - `insight_label` string, nullable
  - `location_resolution` string, nullable
  - `entities` PrismEntity[], nullable
    - `entity_id` integer, required — Carc entity id (representation-scoped)
    - `entity_representation` string, required — Graph representation the id belongs to (e.g. artist, actor). Required — the same real-world entity has a different id per representation.
    - `entity_name` string, required — Resolved entity name
  - `filters` object, nullable
  - `publish_state` 'draft' | 'live'

## Response `200`

Successful Response

- PrismDefinitionResponse
  - `title` string, required — Prism name
  - `category_id` string, uuid, required — First-class category (prism_categories.id)
  - `question` string, nullable — Question this prism answers in the growth (index) view
  - `question_share` string, nullable — Question this prism answers in the share view
  - `note` string, nullable — Short caveat shown as a warning bar at the top of this prism's drawer on the public page. Null/blank = no bar.
  - `insight_id` integer, required — Metric insight id
  - `insight_label` string, required
  - `location_resolution` string — Location grain the framework computes at, as advertised by /prisms/location-resolutions for this insight + entity set
  - `entities` PrismEntity[], required — Entities the prism computes over; at least one
    - `entity_id` integer, required — Carc entity id (representation-scoped)
    - `entity_representation` string, required — Graph representation the id belongs to (e.g. artist, actor). Required — the same real-world entity has a different id per representation.
    - `entity_name` string, required — Resolved entity name
  - `filters` object — Dimension filters from the framework's advertised set, as {filter_key: value}. Blank selections are dropped, not sent as empty lists. Grain / window / aggregate are prism-owned and rejected here.
  - `publish_state` 'draft' | 'live'
  - `id` string, uuid, required
  - `category` string, required
  - `archived_at` string, date-time, nullable
  - `last_refreshed_at` string, date-time, nullable
  - `last_order_id` string, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `created_by` string, nullable
  - `date_window_start` string, date, required
  - `date_window_end` string, date, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api.md) · [All operations](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/carbonarc/carbon-arc-client-admin-api/revisions/a8ca30023371/schema)