---
title: "Publish one of your own environments as a listing [write]"
method: PUT
path: "/environments/{id}/listing"
tags: ["environments"]
---

# Publish one of your own environments as a listing \[write\]

`PUT /environments/{id}/listing`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/environments/{id}/listing`
- Auth: HTTP bearer

Creates or replaces the listing for this environment on the shelf, visible to the caller's workspace until a submission of it is approved. The environment must belong to the caller's workspace. A public listing's handle cannot change (409 `listing_public`). Answers 404 when the shelf is not enabled for this workspace or the environment is not found. Answers 503 `not_migrated` until the shelf migration is applied.

## Path parameters

- `id` string, required

## Request body

- object
  - `handle` string, required: 2 to 40 lower-case letters, digits or underscores; unique across environment listings
  - `name` string, required
  - `tagline` string
  - `description` string
  - `categories` string[]: Defaults to general

## Response `200`

OK

- object
  - `listing` EnvironmentListing, required
    - `id` string, required: The listing id (lst_…)
    - `handle` string, required: Globally unique within environment listings; lower-case letters, digits and underscores
    - `name` string, required
    - `tagline` string, required: One line, at most 140 characters
    - `description` string, required
    - `categories` string[], required
    - `packages` object, nullable, required: The listed environment's package configuration, or null when it has none
    - `tools` object, nullable, required: The listed environment's tool policy, or null when it has none
    - `networking` object, nullable, required: The listed environment's networking configuration, or null when it has none
    - `installs` integer, required: How many workspaces have installed this listing
    - `seller` object, nullable, required: Who published it to other workspaces, by the name they chose; null while it is visible only to its own workspace
      - `name` string, required
    - `visibility` 'workspace' | 'public', required: workspace = visible only to the owning workspace; public = approved, and visible to every workspace the shelf is open to. Other workspaces read and install the approved version; the owner's later edits wait for a new approval
    - `conformance` object, nullable, required: The smoke run the approved version passed; null for a listing that is not public
      - `required_passed` boolean, required: Every required check of the smoke run passed
      - `all_passed` boolean, required
      - `checked_at` string, date-time, required
    - `created_at` string, date-time, required

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/environments/:id/listing/put.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)