POST - Create Template Folder

POST/api/public/template-folders

Create a template folder

Creates a new folder inside the TechWriter Template Library. Provide a folder name and, optionally, the user groups and individual users who should have access. On success the API returns the new folder ID along with the creation timestamp.

Folder names must be unique among root-level folders in the workspace. Use groupIds for team-wide access and userIds for individual exceptions — both arrays may be empty if the folder is private to the creator.

Query parameters

None — this endpoint does not accept any query string parameters.

Request headers

HeaderValueRequiredDescription

AuthorizationBearer {YOUR_BEARER_TOKEN}requiredAccess token used to authenticate the API request.

Accept*/*optionalIndicates the response formats the client can accept.

Content-Typeapplication/jsonrequiredIndicates that the request body is JSON.

Request body

Send a JSON object with the folder name and (optionally) the groups or users that should receive access.

FieldTypeRequiredDescription

namestringrequiredDisplay name of the new template folder. Must be unique among root-level folders.

groupIdsstring[]optionalOptional list of user-group IDs that should receive access to the folder.

userIdsinteger[]optionalOptional list of user IDs (employee numbers) that should receive direct access to the folder. Example: [12734, 5892]. Minimum 0 items.

Response fields

Returned on a successful 201 Created response.

FieldTypeDescription

data.folderIdstringUnique identifier of the new template folder.

data.namestringDisplay name of the created folder, echoed back from the request.

data.createdDatestringFolder creation timestamp in ISO 8601 format.

successbooleanIndicates whether the request completed successfully.

Response codes

The API uses conventional HTTP status codes. 2xx indicate success, 4xx indicate client errors, and 5xx indicate server-side issues.

StatusDescription

201 CreatedTemplate folder was created successfully. The response includes the new folder ID and creation timestamp.

400 Bad RequestThe payload is malformed: missing name, or non-string IDs in groupIds / userIds.

401 UnauthorizedAuthentication failed: missing, invalid, or expired bearer token.

403 ForbiddenThe token is valid but lacks the templates:write scope.

409 ConflictA template folder with the same name already exists at the root level.

422 UnprocessableOne or more group or user IDs could not be resolved in the workspace.

429 Too ManyYou exceeded the rate limit. Retry after the specified delay.

500 Server ErrorAn unexpected error occurred while creating the folder.

503 UnavailableThe service is temporarily down for maintenance or overloaded.

Was this section helpful?

Example request

curl -X POST "{{env_base_uri}}/api/public/template-folders" \
  -H "Authorization: Bearer {YOUR_BEARER_TOKEN}" \
  -H "Accept: */*" \
  -H "Content-Type: application/json" \
  -d 

Example response

201 CreatedTemplate folder was created successfully. The response includes the new folder ID and creation timestamp.

{
  "data": {
    "folderId": "8a921f63-e90b-4296-83b5-2a793817e778",
    "name": "Onboarding Templates",
    "createdDate": "2026-01-30T08:53:05.1504161-08:00"
  },
  "success": true
}

Granting access later

You don't have to assign access at creation time. Send an empty groupIds and userIds to keep the folder private, then share it later through the share endpoint or the Template Library UI.