---
title: "Set or rename the org's slug (repo-first-onramp D6)"
method: POST
path: "/orgs/v1/{org_id}/slug"
tags: ["Org"]
---

# Set or rename the org's slug (repo-first-onramp D6)

`POST /orgs/v1/{org_id}/slug`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/orgs/v1/{org_id}/slug`
- Auth: one of:
  - API key in header `SIGN-IN-WITH-X`
  - HTTP bearer

Owner-only. Claims a globally-unique, address-form slug for the org (`run402::<org-slug>/<repo-name>`), distinct from display_name. A genesis set (the org had no slug yet) is a 201; a rename (the org already had a slug — the old one releases into a ~90-day cooldown behind a typed SLUG_RELEASED refusal, never a redirect) is a 200. The org's FIRST-EVER slug claim is free — no billing wallet required; every later set or rename debits a one-time payable set fee from the org's allowance. `fee_usd_micros` in the response names the real price of THIS call (0 or the fee). Requires Idempotency-Key so a retried claim cannot double-bill. Refused for names on the static reserved list (SLUG_RESERVED) or the curated protected-brands list (SLUG_PROTECTED, available only via manual review), and for a slug already claimed or in cooldown (SLUG_TAKEN / SLUG_RELEASED, the latter naming the successor slug).

## Path parameters

- `org_id` string, uuid, required

## Headers

- `SIGN-IN-WITH-X` string, required
- `Idempotency-Key` string, required

## Request body

- object
  - `slug` string, required: Lowercase [a-z0-9-], no leading/trailing/double hyphen, at most 39 characters. Case-folded at resolution; uppercase is refused at claim time, not silently normalized.

## Response `200`

Renamed — the org already held a different slug

- OrgSlugSetResult
  - `org_id` string, uuid
  - `slug` string
  - `previous_slug` unknown
  - `created` boolean: true for a genesis set (the org had no prior slug); false for a rename or a no-op replay of the org's current slug.
  - `fee_usd_micros` integer: The fee actually charged for THIS call. 0 for the org's free first-ever slug claim (or a no-op idempotent replay); the slug set fee otherwise (every later set or rename).

## Other responses

- `201`: Genesis set — the org had no slug yet
- `400`: Grammar violation (VALIDATION_FAILED) or missing Idempotency-Key (IDEMPOTENCY_KEY_REQUIRED / IDEMPOTENCY_KEY_INVALID)
- `403`: Owner role required (FORBIDDEN); reserved (SLUG_RESERVED); protected brand (SLUG_PROTECTED); insufficient allowance (ALLOWANCE_INSUFFICIENT, names required_usd_micros — never returned for an org's free first-ever claim); no billing wallet (ORG_HAS_NO_BILLING_WALLET, names required_usd_micros — never returned for an org's free first-ever claim)
- `409`: Already taken by another org (SLUG_TAKEN), or in cooldown naming the successor (SLUG_RELEASED)

---

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