Skip to main content
POST
https://app.tokencraft.dev/api/v1
/
workspaces
Create Workspace
curl --request POST \
  --url https://app.tokencraft.dev/api/v1/workspaces \
  --header 'Authorization: Bearer <token>'

​
Create Workspace

Creates a new workspace for the authenticated user.
Write access policy - This endpoint requires the write:tokens scope and API write access on the token owner account. Workspace creation is blocked when the owner is at/above their workspace plan limit (existing workspaces stay accessible).

​
Endpoint

POST /workspaces

​
Authentication

Requires a valid API token in the Authorization header.

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer tokenYes
Content-Typeapplication/jsonYes

​
Body Parameters

ParameterTypeRequiredDescription
namestringYesWorkspace name (max 255 characters)
descriptionstringNoOptional description

​
Request Body

{
  "name": "Design System",
  "description": "Main product design system"
}

​
Response

​
Success Response

Status: 201 Created 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Design System",
  "description": "Main product design system",
  "user_id": "user-123",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

​
Examples

curl -X POST https://app.tokencraft.dev/api/v1/workspaces \
  -H "Authorization: Bearer tkc_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Design System",
    "description": "Main product design system"
  }'

​
Error Responses

​
400 Bad Request

{
  "error": "Name is required and must be a non-empty string"
}
Causes:
  • Missing or empty name field
  • name exceeds 255 characters
  • Invalid field types

​
401 Unauthorized

{
  "error": "Invalid API token"
}

​
403 Forbidden

{
  "error": "API write access requires PRO or TEAM plan. Upgrade your plan to create resources via API."
}
Causes:
  • Owner plan does not include API write access
  • Owner reached workspace creation limit on current plan

​
500 Internal Server Error

{
  "error": "Internal server error"
}

​
Validation Rules

  • name: Required, non-empty string, max 255 characters
  • description: Optional string

​
Next Steps

Update Workspace

Update workspace details

Create Tokenset

Add tokensets to your workspace