Usernames and workspace slugs

OpenDocs has two human-readable identifiers and they do different things. They're easy to confuse, so the API exposes a check endpoint for each.

	Username	Workspace slug
What it identifies	A person	A workspace (team or solo)
Where it appears in URLs	opendocs.cc/@<username> (profile page)	opendocs.cc/<workspace-slug>/<post-slug> (published documents)
Scope	Global across the platform	Global across the platform
Chosen at	Onboarding step 1	Onboarding step 2 / when creating a new workspace
Check endpoint	GET /api/v1/usernames/check	GET /api/v1/workspace/check-slug
Normalization	lowercase	lowercase, - separators

tip

If you're building CLI/agent tooling and need to construct the URL a newly-published document will live at, use the workspace slug from GET /api/v1/me → onboarding.workspace.slug, not the username.

GET /api/v1/usernames/check

Check whether a username is valid, normalized, and currently available.

Auth

No auth required.

Request

GET /api/v1/usernames/check?username=pat

Query parameters

Name	Type	Required	Description
username	string	Yes	The username to validate

Success response

{
  "available": true,
  "normalized": "pat",
  "reason": null
}

Invalid or reserved response

{
  "available": false,
  "normalized": "docs",
  "reason": "reserved"
}

reason can be:

• invalid — failed format validation (length, allowed characters)
• reserved — matches a reserved route name like docs, pricing, faq
• null — when available: true

Notes

• Usernames are normalized to lowercase.
• Reserved route names (docs, pricing, faq, and similar) are blocked.
• The username is used as the personal-profile path (opendocs.cc/@<username>), not the document URL.

GET /api/v1/workspace/check-slug

Check whether a workspace slug is valid, normalized, and currently available. This is the check you want for anything URL-related — published documents live under the workspace slug.

Auth

Session auth required (onboarding flow).

Request

GET /api/v1/workspace/check-slug?slug=acme-docs

Query parameters

Name	Type	Required	Description
slug	string	Yes	The workspace slug to validate

Success response

{
  "available": true,
  "normalized": "acme-docs"
}

Unavailable response

{
  "available": false,
  "reason": "Workspace slug is already taken."
}

Notes

• Workspace slugs are normalized to lowercase and allow a–z, 0–9, and -.
• Reserved slugs (shared with reserved usernames — docs, pricing, faq, and similar) are blocked.
• The workspace slug is what appears in every published document's URL: opendocs.cc/<workspace-slug>/<post-slug>.

Related pages

• GET /api/v1/me — returns the current username AND workspace slug
• Workspaces API — changing a workspace slug after onboarding
• Onboarding and profile — the flow that chooses both identifiers in the first place