Routes

Create or replace a route

Creates the route at path, or replaces it when it exists. When contentKey is omitted it is derived from the path. To make a redirect, send purpose: "redirect" and a root-relative redirectTo in the same call. A redirect cannot also carry contentKey, layout, experiment, nav or navLabel, and redirectTo / redirectStatus need purpose: "redirect". The home page is …/routes/ (trailing slash). Other paths are sent without the leading slash, for example …/routes/blog/launch for /blog/launch. The change is staged to the draft — publish to make it live.

put/api/v1/sites/{slug}/routes/{path}

Request

  • Base URL: https://api.dotsy.ai
  • URL: https://api.dotsy.ai/api/v1/sites/{slug}/routes/{path}
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Path parameters

slugstring required
Example:acme-studio

Site slug or site id (UUID). An old slug answers 301/308 and a site id 307 to the canonical slug path.

pathstring required

Percent-encode each segment; '/' may be sent raw or as %2F. Keys may contain '/'.

Request body

contentKeystring nullable

Explicit content key (defaults to a path-derived key when omitted). null clears an explicit key back to that path default — same as omitting it, but usable on a PATCH to undo a prior set.

layoutstring nullable

Layout NAME, bare: "default" for layouts/default.html — not the file key. It must already exist as layouts/<name>.html (400 layout_not_found otherwise). null removes the layout.

titlestring nullable
varsobject nullable
purposestring nullable
redirectTostring nullable

Redirect target, a root-relative path (/…). Required when purpose is "redirect". null clears it — only valid once purpose stops being "redirect" (a redirect route always needs a target).

preserveQueryboolean nullable

Append the visitor's original query string to the redirect target (default true on a redirect). null clears an explicit override.

navLabelstring nullable

DEPRECATED — use put_menu_item / menu API. Menu link text for <dotsy-nav> (separate from title). Still accepted during transition and synced to menu items.

noindexboolean nullable

Exclude from sitemap/RSS; inject noindex meta (0.69).

Example request

{
  "title": "About us",
  "layout": "layouts/main.html"
}

Response

The route existed and was replaced (staged).

pathstring required

The URL path. The home page is /. A :param segment makes a pattern route.

contentKeystring nullable required

The content key this route serves. Null on a redirect, and on a route with no explicit key (it then serves the key derived from its path).

layoutstring nullable required

Layout file key, for example layouts/main.html.

titlestring nullable required

Page title.

varsobject nullable required

Template variables passed to the layout.

purposestring nullable required

redirect for a redirect route, otherwise null.

redirectTostring nullable required

Redirect target, a root-relative path. Set only when purpose is redirect.

preserveQueryboolean nullable required

Whether a redirect appends the visitor's query string to its target. Null means the default (true).

navLabelstring nullable required

Deprecated. Menu link text — use the menu API instead.

noindexboolean nullable

True when the page is excluded from the sitemap and marked noindex.

createdBy'person' | 'ai' | 'key' | 'move' nullable

Who made this route a redirect: a signed-in person, an ai (MCP OAuth), an API key, or a page move. Present only on redirects.

createdByIdstring nullable

The user id when createdBy is person.

updatedAtnumber required

Last change, Unix ms.

createdboolean

PUT only: true when the route did not exist before.

publishedfalse required

Always false: a route change is staged until you publish.

hintstring required

Example response

{
  "path": "/about",
  "contentKey": "about.html",
  "layout": "layouts/main.html",
  "title": "About us",
  "hint": "Changes staged to draft — call publish_site to go live."
}

Changes

No recorded changes to this operation across all 1 revision of this API.