---
topic: rename
connector: "app_danger_zone · rename_app; read_app · rename_status"
api: "POST https://ship.embarko.ai/api/apps/{app-name}/slug-change"
needs_human: "Confirm first: links already shared will stop working."
requires: [claim]
---

[← Guide home](https://embarko.ai/docs)

# Change the web address

**On this page:** With the connector, Over HTTP, Errors, What to tell the person

> Plain words unless the person is a developer. Never invent a link, name or code. [Rules](https://embarko.ai/docs/prerequisites) Needs first: [claim](https://embarko.ai/docs/claim) (over HTTP only).

Changes the app's address. The old address stops working and does not redirect, and someone else can claim it. Custom domains keep working. Changing only the display name is a different, harmless call.

**Connector:** app_danger_zone · rename_app; read_app · rename_status

**Done when:** The new address opens the app, and you use the new name from now on.

**With the connector**

1. Confirm with the person. Call app_danger_zone { action: "rename_app", appName, newName }. If terminal is false, poll read_app { action: "rename_status", projectId }.
2. Use the new name in every call from now on.

**Over HTTP**

1. Confirm with the person. POST https://ship.embarko.ai/api/apps/{app-name}/slug-change with {"newName": "..."} and the token.
2. A live app replies 202 with projectId: poll GET https://ship.embarko.ai/api/slug-changes/{project-id} until terminal is true. It takes minutes. From then on use the name in the reply's deployWith.
3. Display name only: PATCH https://ship.embarko.ai/api/apps/{app-name} with {"name": "My App"}. The address does not change.

**Errors**

| Code | Status | Retry | What to do |
| --- | --- | --- | --- |
| `app_name_taken / app_name_reserved` | 409 | No | Pick another name. |
| `deploy_in_progress / rename_in_progress` | 409 | Later | Wait for it to finish. |
| `slug_change_cooldown` | 429 | Later | One change per app per week; retryAfterMs says when. |
| `app_state_unknown` | 503 | Once | Retry once after 2 seconds. |
| `rename_failed` | 502 | Once | Nothing changed. Try once more. |
| `rename_desynced` | 500 | No | Needs the Embarko team: report it. |

**What to tell the person**

- confirm: "Your app will move to {new}.embarko.app. The old link stops working right away with no redirect, and someone else could take the old name. Your custom domain and Showcase listing move with it. You can change the address only once a week. Go ahead?"
- done: "Done: your app is now at {link}."

**Next:** Ask first, then rename.

**Related:** [showcase](https://embarko.ai/docs/showcase) · [custom-domain](https://embarko.ai/docs/custom-domain)

---

[Guide home](https://embarko.ai/docs) · JSON: add .json