---
title: "Create Catalog Item"
method: POST
path: "/v1/registries/{registry_id}/items"
tags: ["v1", "protected", "registries"]
---

# Create Catalog Item

`POST /v1/registries/{registry_id}/items`

Publish one definition without putting catalog data in the OSS image.

## Path parameters

- `registry_id` string, uuid, required

## Request body

- CatalogItemCreate — Definition published directly into a platform-managed catalog.
  - `description` string, nullable
  - `external_id` string, required
  - `name` string, required
  - `recommendation_rank` integer, nullable — Curation position within this registry; lower comes first. Omit to publish after the registry's existing items.
  - `spec` object
  - `tags` string[]
  - `version` string, nullable

## Response `201`

Successful Response

- RegistryItemResponse
  - `category` string, nullable
  - `created_at` string, required
  - `description` string, nullable, required
  - `external_id` string, required
  - `featured` boolean
  - `id` string, uuid, required
  - `installed_entity_id` string, uuid, nullable, required
  - `installed_version` string, nullable, required
  - `name` string, required
  - `registry_id` string, uuid, required
  - `spec` object, required
  - `tags` string[], required
  - `update_available` boolean, required
  - `updated_at` string, required
  - `version` string, nullable, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-21** `11817368931f` — 1 info
  - added the new optional request property `recommendation_rank`
- **2026-09-09** `50200825493e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/agentarea/apis/agentarea-api/changes/v1/registries/:registry_id/items/post.md)

---

[API](https://skmtc.dev/agentarea/apis/agentarea-api.md) · [All operations](https://skmtc.dev/agentarea/apis/agentarea-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentarea/apis/agentarea-api/revisions/7eafe882ff77?raw)