---
title: "Create a new catalog entity"
method: POST
path: "/api/rest/v1/catalog"
tags: ["Catalog"]
---

# Create a new catalog entity

`POST /api/rest/v1/catalog`

## Request

- Base URL: `https://app.componecat.ai`
- URL: `https://app.componecat.ai/api/rest/v1/catalog`
- Auth: none required

`fieldValues` must satisfy the kind's field definitions: unknown keys, wrong JSON types and
missing required fields are rejected with `422`. A plan's entity limit is reported as `402`.

## Request body

- CreateCatalogEntityRequest: Create catalog entity request body.
  - `displayName` string, required: Human-readable name (1–250 characters).
  - `kindId` string, uuid, required: ID of the entity kind definition (see `/entity-kind-definitions`).
  - `ownerId` string, uuid, required: ID of the owning team (see `/teams`).
  - `lifecycle` 'EXPERIMENTAL' | 'DEVELOPMENT' | 'PRODUCTION' | 'DEPRECATED' | 'RETIRED', required: Lifecycle stage.
  - `description` string, required: Human-readable description (1–500 characters).
  - `name` string, nullable: URL-safe identifier (lowercase slug, max 250 characters). Generated from `displayName` when omitted. Must be unique per kind + namespace.
  - `namespace` string, nullable: Optional namespace: lowercase alphanumeric with hyphens, not starting or ending with a hyphen, max 100 characters.
  - `tags` string[], nullable: Free-form tags for categorization.
  - `repository` string, nullable: Source repository URL (HTTPS GitHub, GitLab or Bitbucket, including owner and repository). Only accepted for kinds with repositories enabled (`hasRepository` on the kind definition); any other kind rejects it with `422`.
  - `fieldValues` object, nullable: Kind-specific custom field values, as a JSON object keyed by each field definition's `key` (not an array). Send every value in its native JSON type matching the field's type: string (Text, Date, Url, Select, User, Team), number (Number), boolean (Boolean), array of strings (MultiSelect, Tag), or any JSON value (Json). Keys must resolve to field definitions assigned to the entity's kind; unknown keys are rejected.

## Response `201`

Created

- RestApiResponseOfCatalogEntityDetail: Standard REST API response envelope for a single resource.
  - `data` CatalogEntityDetail, required: Catalog entity detail view -- full fields for single-resource responses.
    - `id` string, uuid, required: The entity ID.
    - `name` string, required: URL-safe identifier (lowercase slug), unique per kind + namespace. Together with the kind key and namespace it forms the entity ref, e.g. `component://payments/payment-gateway`.
    - `namespace` string, nullable, required: Optional logical grouping namespace. Null when the entity has none.
    - `displayName` string, required: Human-readable name.
    - `kindId` string, uuid, required: ID of the entity kind definition (see `/entity-kind-definitions`).
    - `ownerId` string, uuid, required: ID of the owning team (see `/teams`).
    - `lifecycle` 'EXPERIMENTAL' | 'DEVELOPMENT' | 'PRODUCTION' | 'DEPRECATED' | 'RETIRED', required: Lifecycle stage.
    - `description` string, required: Human-readable description.
    - `tags` string[], required: Free-form tags for categorization.
    - `repository` string, nullable, required: Linked source repository URL (HTTPS GitHub, GitLab or Bitbucket). Only kinds with repositories enabled have one; null otherwise.
    - `fields` object, nullable, required: Current custom field values as a JSON object keyed by field definition `key`, with native JSON value types — the same shape accepted by the create/update `fieldValues` input, so a value read back can be sent straight into an update. An empty object when no field values are set.
    - `organizationId` string, uuid, required: ID of the organization that owns the entity.
    - `createdAt` string, date-time, required: When the entity was created.
    - `updatedAt` string, date-time, required: When the entity was last updated.
    - `ownerName` string, nullable: Name of the owning team.
    - `ownerExternalId` string, nullable: Identifier of the owning team in the external system that manages it (e.g. the Atlassian team id); null for a team created in the catalog.
    - `ownerExternalSource` string, nullable: The external system that manages the owning team (e.g. `Atlassian`); null for a team created in the catalog.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Entity
- `429`: Too Many Requests

---

[API](https://skmtc.dev/componecat/apis/componecat-rest-api.md) · [All operations](https://skmtc.dev/componecat/apis/componecat-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/componecat/apis/componecat-rest-api/revisions/6c53d4984720?raw)