--- title: Create a namespace slug: api-documentation/create-a-namespace docTags: createdAt: 2026-10-09T16:36:44.630Z --- { "id": "DjzcN0S-sVXRPfeR1o4mh", "type": "api-oas-v2", "data": { "method": "POST", "url": "http://localhost:8080/idgen/namespaces", "servers": [ { "url": "{baseUrl}/idgen/namespaces", "description": "The API gateway, or the service itself (port 8080).", "variables": { "baseUrl": { "default": "http://localhost:8080", "description": "Scheme and host, e.g. https://. No trailing slash." } } } ], "name": "Create a namespace", "description": "

Creates a namespace in the caller's tenant's namespaces with its first format version (version 1), a DRAFT unless activate is true. Needs idgen.namespaces.write.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "The namespace and its first version.", "customType": "CreateNamespaceRequest", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "

The name callers use: ^[a-z][a-z0-9._-]{0,63}$. Names of deleted namespaces are never reused.

" }, { "name": "description", "kind": "optional", "type": "string", "description": "Free text for administrators." }, { "name": "version", "kind": "required", "type": "object", "description": "

A new ID format. It is validated (every violation is reported together) and must be disjoint from every earlier version of the namespace, unless it continues one.

", "modelRef": "#/components/schemas/VersionDraftDto", "customType": "VersionDraftDto", "schema": [ { "name": "separator", "kind": "required", "type": "string", "description": "

Placed between consecutive segments: 0-3 printable characters, may be empty.

" }, { "name": "segments", "kind": "optional", "type": "array", "description": "

The ordered segments; at least one must be dynamic (a sequence or UUID).

", "modelRef": "#/components/schemas/SegmentDto", "customType": "SegmentDto[]", "schema": [ { "name": "type", "kind": "required", "type": "string", "description": "

STATIC, INTEGER_SEQUENCE, STRING_SEQUENCE or UUID.

" }, { "name": "value", "kind": "optional", "type": "string", "description": "

STATIC: the literal text (printable ASCII, no spaces).

" }, { "name": "start", "kind": "optional", "type": "integer", "description": "

INTEGER_SEQUENCE: the first value (>= 0). Required.

", "format": "int64" }, { "name": "end", "kind": "optional", "type": "integer", "description": "

INTEGER_SEQUENCE: the last value (inclusive). Only the leftmost dynamic segment of a version may omit it (unbounded).

", "format": "int64" }, { "name": "step", "kind": "optional", "type": "integer", "description": "

INTEGER_SEQUENCE: the increment between consecutive values. Default 1.

", "format": "int64" }, { "name": "padding", "kind": "optional", "type": "integer", "description": "

INTEGER_SEQUENCE: the minimum width, left-padded with zeros (0-19). Default 0.

", "format": "int32" }, { "name": "charset", "kind": "optional", "type": "string", "description": "

STRING_SEQUENCE: NUMERIC, UPPER, LOWER, ALPHANUMERIC_UPPER, ALPHANUMERIC, ALPHANUMERIC_NO_AMBIGUOUS (Crockford) or CUSTOM.

" }, { "name": "chars", "kind": "optional", "type": "string", "description": "

STRING_SEQUENCE with charset CUSTOM: at least 2 distinct printable characters, in sequence order.

" }, { "name": "length", "kind": "optional", "type": "integer", "description": "

STRING_SEQUENCE: the number of characters (1-16).

", "format": "int32" }, { "name": "startText", "kind": "optional", "type": "string", "description": "

STRING_SEQUENCE: the first value, exactly length characters of the charset. Default: the lowest.

" }, { "name": "endText", "kind": "optional", "type": "string", "description": "

STRING_SEQUENCE: the last value (inclusive), exactly length characters of the charset. Default: the highest.

" } ] }, { "name": "blockSize", "kind": "optional", "type": "integer", "description": "

How many positions a node reserves at once (10-100000, default 1000). Larger means fewer database round trips and bigger gaps after restarts.

", "format": "int32" }, { "name": "continuesFrom", "kind": "optional", "type": "integer", "description": "

An earlier version whose sequence this one carries on. Its dynamic segments must be identical; use it to change a static part without restarting the numbering.

", "format": "int32" } ] }, { "name": "activate", "kind": "optional", "type": "boolean", "description": "

true activates version 1 immediately; otherwise it is created as a DRAFT. Default false.

" } ], "modelRef": "#/components/schemas/CreateNamespaceRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "bearerAuth", "name": "bearerAuth", "kind": "optional", "type": "http", "description": "

A JWT from authentication-svc. The tenant comes from the token.

", "scheme": "bearer" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "201", "description": "The new namespace.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "

A namespace (or template): a stable name with numbered, immutable format versions.

", "customType": "NamespaceDto", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "The namespace name." }, { "name": "description", "kind": "optional", "type": "string", "description": "Free text for administrators." }, { "name": "status", "kind": "required", "type": "string", "description": "ACTIVE or DISABLED." }, { "name": "currentVersion", "kind": "optional", "type": "integer", "description": "

The version IDs come from right now; absent while no version is active.

", "format": "int32" }, { "name": "createdAt", "kind": "required", "type": "string", "description": "When the namespace was created.", "format": "date-time" }, { "name": "updatedAt", "kind": "required", "type": "string", "description": "When the namespace was last updated.", "format": "date-time" }, { "name": "links", "kind": "required", "type": "map", "description": "

Related resources: self, versions and, for namespaces, ids (paths under /idgen).

", "example": "", "customType": "map", "schema": [] } ], "modelRef": "#/components/schemas/NamespaceDto", "isExpanded": true } ] }, { "statusCode": "400", "description": "

INVALID_REQUEST: a malformed path or body value, or an invalid name.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "

The body of every error response. Branch on error, never on message.

", "customType": "ErrorDto", "schema": [ { "name": "error", "kind": "required", "type": "string", "description": "

The machine-readable error code, e.g. NAMESPACE_NOT_FOUND or FORMAT_OVERLAP.

" }, { "name": "message", "kind": "required", "type": "string", "description": "

A human-readable explanation.

" }, { "name": "status", "kind": "required", "type": "integer", "description": "

The HTTP status code, repeated.

", "format": "int32" }, { "name": "details", "kind": "required", "type": "map", "description": "

Structured context: retryable (whether the same request can succeed later) and, depending on the code, namespace, version, templateExists, conflictingVersion and exampleId.

", "example": "", "customType": "map", "schema": [] }, { "name": "links", "kind": "required", "type": "map", "description": "

Related resources, e.g. namespace (paths under /idgen).

", "example": "", "customType": "map", "schema": [] } ], "modelRef": "#/components/schemas/ErrorDto", "isExpanded": true } ] }, { "statusCode": "401", "description": "

UNAUTHENTICATED: missing, expired or invalid credentials.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "

The body of every error response. Branch on error, never on message.

", "customType": "ErrorDto", "schema": [ { "name": "error", "kind": "required", "type": "string", "description": "

The machine-readable error code, e.g. NAMESPACE_NOT_FOUND or FORMAT_OVERLAP.

" }, { "name": "message", "kind": "required", "type": "string", "description": "

A human-readable explanation.

" }, { "name": "status", "kind": "required", "type": "integer", "description": "

The HTTP status code, repeated.

", "format": "int32" }, { "name": "details", "kind": "required", "type": "map", "description": "

Structured context: retryable (whether the same request can succeed later) and, depending on the code, namespace, version, templateExists, conflictingVersion and exampleId.

", "example": "", "customType": "map", "schema": [] }, { "name": "links", "kind": "required", "type": "map", "description": "

Related resources, e.g. namespace (paths under /idgen).

", "example": "", "customType": "map", "schema": [] } ], "modelRef": "#/components/schemas/ErrorDto", "isExpanded": true } ] }, { "statusCode": "403", "description": "

FORBIDDEN: the caller lacks the idgen.namespaces.write permission, or its tenant or site scope does not match.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "

The body of every error response. Branch on error, never on message.

", "customType": "ErrorDto", "schema": [ { "name": "error", "kind": "required", "type": "string", "description": "

The machine-readable error code, e.g. NAMESPACE_NOT_FOUND or FORMAT_OVERLAP.

" }, { "name": "message", "kind": "required", "type": "string", "description": "

A human-readable explanation.

" }, { "name": "status", "kind": "required", "type": "integer", "description": "

The HTTP status code, repeated.

", "format": "int32" }, { "name": "details", "kind": "required", "type": "map", "description": "

Structured context: retryable (whether the same request can succeed later) and, depending on the code, namespace, version, templateExists, conflictingVersion and exampleId.

", "example": "", "customType": "map", "schema": [] }, { "name": "links", "kind": "required", "type": "map", "description": "

Related resources, e.g. namespace (paths under /idgen).

", "example": "", "customType": "map", "schema": [] } ], "modelRef": "#/components/schemas/ErrorDto", "isExpanded": true } ] }, { "statusCode": "409", "description": "

NAMESPACE_ALREADY_EXISTS: the name is taken, or was used by a deleted namespace.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "

The body of every error response. Branch on error, never on message.

", "customType": "ErrorDto", "schema": [ { "name": "error", "kind": "required", "type": "string", "description": "

The machine-readable error code, e.g. NAMESPACE_NOT_FOUND or FORMAT_OVERLAP.

" }, { "name": "message", "kind": "required", "type": "string", "description": "

A human-readable explanation.

" }, { "name": "status", "kind": "required", "type": "integer", "description": "

The HTTP status code, repeated.

", "format": "int32" }, { "name": "details", "kind": "required", "type": "map", "description": "

Structured context: retryable (whether the same request can succeed later) and, depending on the code, namespace, version, templateExists, conflictingVersion and exampleId.

", "example": "", "customType": "map", "schema": [] }, { "name": "links", "kind": "required", "type": "map", "description": "

Related resources, e.g. namespace (paths under /idgen).

", "example": "", "customType": "map", "schema": [] } ], "modelRef": "#/components/schemas/ErrorDto", "isExpanded": true } ] }, { "statusCode": "422", "description": "

INVALID_FORMAT: the first version is invalid; message lists every violation.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "

The body of every error response. Branch on error, never on message.

", "customType": "ErrorDto", "schema": [ { "name": "error", "kind": "required", "type": "string", "description": "

The machine-readable error code, e.g. NAMESPACE_NOT_FOUND or FORMAT_OVERLAP.

" }, { "name": "message", "kind": "required", "type": "string", "description": "

A human-readable explanation.

" }, { "name": "status", "kind": "required", "type": "integer", "description": "

The HTTP status code, repeated.

", "format": "int32" }, { "name": "details", "kind": "required", "type": "map", "description": "

Structured context: retryable (whether the same request can succeed later) and, depending on the code, namespace, version, templateExists, conflictingVersion and exampleId.

", "example": "", "customType": "map", "schema": [] }, { "name": "links", "kind": "required", "type": "map", "description": "

Related resources, e.g. namespace (paths under /idgen).

", "example": "", "customType": "map", "schema": [] } ], "modelRef": "#/components/schemas/ErrorDto", "isExpanded": true } ] }, { "statusCode": "500", "description": "

INTERNAL_ERROR: an unexpected failure. Retry once, then report it with the x-request-id.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "

The body of every error response. Branch on error, never on message.

", "customType": "ErrorDto", "schema": [ { "name": "error", "kind": "required", "type": "string", "description": "

The machine-readable error code, e.g. NAMESPACE_NOT_FOUND or FORMAT_OVERLAP.

" }, { "name": "message", "kind": "required", "type": "string", "description": "

A human-readable explanation.

" }, { "name": "status", "kind": "required", "type": "integer", "description": "

The HTTP status code, repeated.

", "format": "int32" }, { "name": "details", "kind": "required", "type": "map", "description": "

Structured context: retryable (whether the same request can succeed later) and, depending on the code, namespace, version, templateExists, conflictingVersion and exampleId.

", "example": "", "customType": "map", "schema": [] }, { "name": "links", "kind": "required", "type": "map", "description": "

Related resources, e.g. namespace (paths under /idgen).

", "example": "", "customType": "map", "schema": [] } ], "modelRef": "#/components/schemas/ErrorDto", "isExpanded": true } ] }, { "statusCode": "503", "description": "

AUTH_UNAVAILABLE or BACKEND_UNAVAILABLE (both retryable): retry with backoff.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "

The body of every error response. Branch on error, never on message.

", "customType": "ErrorDto", "schema": [ { "name": "error", "kind": "required", "type": "string", "description": "

The machine-readable error code, e.g. NAMESPACE_NOT_FOUND or FORMAT_OVERLAP.

" }, { "name": "message", "kind": "required", "type": "string", "description": "

A human-readable explanation.

" }, { "name": "status", "kind": "required", "type": "integer", "description": "

The HTTP status code, repeated.

", "format": "int32" }, { "name": "details", "kind": "required", "type": "map", "description": "

Structured context: retryable (whether the same request can succeed later) and, depending on the code, namespace, version, templateExists, conflictingVersion and exampleId.

", "example": "", "customType": "map", "schema": [] }, { "name": "links", "kind": "required", "type": "map", "description": "

Related resources, e.g. namespace (paths under /idgen).

", "example": "", "customType": "map", "schema": [] } ], "modelRef": "#/components/schemas/ErrorDto", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "rdWXAQIinCcp1RKW4f6DR", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url http://localhost:8080/idgen/namespaces \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"name\": \"\",\n \"version\": {\n \"separator\": \"\",\n \"segments\": [\n {\n \"type\": \"\"\n }\n ]\n }\n }'" }, { "id": "x-7BkPTeTb_EWLRgWFQuF", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"name\": \"\",\n \"version\": {\n \"separator\": \"\",\n \"segments\": [\n {\n \"type\": \"\"\n }\n ]\n }\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"http://localhost:8080/idgen/namespaces\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "mDNO776pOFr8X5zuqtr5s", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"http://localhost:8080/idgen/namespaces\")\n\nhttp = Net::HTTP.new(url.host, url.port);\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"name\": \"\",\n \"version\": {\n \"separator\": \"\",\n \"segments\": [\n {\n \"type\": \"\"\n }\n ]\n }\n})\n\nresponse = http.request(request)\nputs response.read_body\n" }, { "id": "h34qiLQC5dNzWM-xYSI9O", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"http://localhost:8080/idgen/namespaces\"\n\npayload = json.dumps({\n \"name\": \"\",\n \"version\": {\n \"separator\": \"\",\n \"segments\": [\n {\n \"type\": \"\"\n }\n ]\n }\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "rdWXAQIinCcp1RKW4f6DR" }, "results": { "languages": [ { "id": "4J3pbeNRSEK810losYYOw", "language": "201", "code": "// The new namespace.\n{\n \"name\": \"\",\n \"description\": \"\",\n \"status\": \"\",\n \"currentVersion\": \"\",\n \"createdAt\": \"\",\n \"updatedAt\": \"\",\n \"links\": \"\"\n}" }, { "id": "WwCz5AbPKLjibmfbi3Z_I", "language": "400", "code": "// INVALID_REQUEST: a malformed path or body value, or an invalid name.\n{\n \"error\": \"\",\n \"message\": \"\",\n \"status\": \"\",\n \"details\": \"\",\n \"links\": \"\"\n}" }, { "id": "gyJlk4uFlZZXRahLr1B7W", "language": "401", "code": "// UNAUTHENTICATED: missing, expired or invalid credentials.\n{\n \"error\": \"\",\n \"message\": \"\",\n \"status\": \"\",\n \"details\": \"\",\n \"links\": \"\"\n}" }, { "id": "nTgO5KCU5Fwmtvq7xjGGd", "language": "403", "code": "// FORBIDDEN: the caller lacks the idgen.namespaces.write permission, or its tenant or site scope does not match.\n{\n \"error\": \"\",\n \"message\": \"\",\n \"status\": \"\",\n \"details\": \"\",\n \"links\": \"\"\n}" }, { "id": "42k9bA57LYilmUraiVo8I", "language": "409", "code": "// NAMESPACE_ALREADY_EXISTS: the name is taken, or was used by a deleted namespace.\n{\n \"error\": \"\",\n \"message\": \"\",\n \"status\": \"\",\n \"details\": \"\",\n \"links\": \"\"\n}" }, { "id": "XiPjzDGE7yIdRGkLe173g", "language": "422", "code": "// INVALID_FORMAT: the first version is invalid; message lists every violation.\n{\n \"error\": \"\",\n \"message\": \"\",\n \"status\": \"\",\n \"details\": \"\",\n \"links\": \"\"\n}" }, { "id": "K-89mP6WzwOb_fMnQtKyV", "language": "500", "code": "// INTERNAL_ERROR: an unexpected failure. Retry once, then report it with the x-request-id.\n{\n \"error\": \"\",\n \"message\": \"\",\n \"status\": \"\",\n \"details\": \"\",\n \"links\": \"\"\n}" }, { "id": "mnvjllZOo-fvDMh8KxAog", "language": "503", "code": "// AUTH_UNAVAILABLE or BACKEND_UNAVAILABLE (both retryable): retry with backoff.\n{\n \"error\": \"\",\n \"message\": \"\",\n \"status\": \"\",\n \"details\": \"\",\n \"links\": \"\"\n}" } ], "selectedLanguageId": "4J3pbeNRSEK810losYYOw" } }, "children": [ { "text": "" } ] }