---
title: "Publish an agent into a registry"
method: POST
path: "/registries/{slug}/agents"
tags: ["Registries"]
---

# Publish an agent into a registry

`POST /registries/{slug}/agents`

Publish an agent into a registry

## Headers

- `Idempotency-Key` string

## Request body

- object — Publish an agent into a registry. When display_name is present the agent identity is defined (create-or-get by address) in the same call before publishing; omit the define fields to publish an already-defined agent.
  - `address` string, required
  - `handle` string, required — The registry-scoped name to list the agent under.
  - `display_name` string — Present to define the agent identity before publishing (define + publish in one call).
  - `endpoint_id` string, uuid — Optional, only used when defining. Omit to resolve the endpoint from the address's routing.
  - `title` string, nullable
  - `description` string, nullable
  - `tags` string[]

## Response `200`

Idempotent replay of an existing publication

- object
  - `success` true, required
  - `data` object, required
    - `status` 'approved' | 'requested', required — approved lists immediately; requested pends owner approval.
    - `handle` string, required
    - `idempotent_replay` boolean, required — True when the publish matched an existing identical publication.

## Other responses

- `201` — Published (approved) or request created (requested)
- `401` — Invalid or missing API key
- `403` — Authenticated caller lacks permission for the operation
- `404` — Resource not found
- `409` — The request conflicts with the current state of the resource
- `422` — The request was well-formed but could not be processed. For Payments this covers a missing payout address, a failed payment verification, a spend-policy decline, or an expired challenge; `error.code` distinguishes them.

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) · [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/primitive/primitive-api/revisions/c2299d28022c/schema)