---
title: "Create Prism"
method: POST
path: "/api/v1/admin/prisms"
tags: ["Admin APIs", "prisms"]
---

# Create Prism

`POST /api/v1/admin/prisms`

Create a prism. A live prism is computed immediately through the real
purchase path; if that fails (e.g. provider restriction) nothing is kept,
so a tile never exists without data behind it.

## Request body

- PrismDefinitionCreate
  - `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'

## 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)