POST /api/spaces

Spaces API - Create Space 🏗️

This endpoint lets authenticated users create a new Space. Spaces serve as self-contained workspaces for organizing and sharing documentation in DocuWriter.ai.

Authentication 🔒

Requests must include a valid Bearer token. The Space will be created under the authenticated user's account and subject to their subscription plan limits.

Endpoint

POST /api/spaces

---

Request

Headers

• Authorization: Bearer <token> (required)
• Accept: application/json (required)

Body Parameters

Field	Type	Required	Validation	Description
name	string	yes	max:250	Space name
description	string	no	—	Space description
is_public	boolean	no	—	Visibility flag (true = public, false = private). Defaults to false.
slug	string	conditional	unique, max:255	URL-friendly slug for public Spaces. Auto-generated from name if not provided.

Space Quota Limits

Space creation is subject to subscription plan limits:

• Starter Plan: 1 space
• Pro Plan: 5 spaces
• Enterprise/Unlimited Plans: 999,999 spaces

Attempting to create a Space beyond your plan's limit returns a 403 error.

Example Request (Private Space)

{
  "name": "Project Documentation",
  "description": "Internal project docs",
  "is_public": false
}

Example Request (Public Space)

{
  "name": "API Documentation",
  "description": "Public API reference",
  "is_public": true,
  "slug": "api-docs"
}

---

Response

Success (201 Created)

{
  "success": true,
  "data": {
    "id": 123,
    "name": "Project Documentation",
    "description": "Internal project docs",
    "is_public": false,
    "slug": null,
    "sort": 5,
    "user_id": 456,
    "created_at": "2025-09-17T12:00:00Z"
  },
  "message": "Space created successfully"
}

Success with Public URL (201 Created)

For public Spaces, the response includes a public_url field:

{
  "success": true,
  "data": {
    "id": 124,
    "name": "API Documentation",
    "description": "Public API reference",
    "is_public": true,
    "slug": "api-docs",
    "sort": 6,
    "user_id": 456,
    "created_at": "2025-09-17T12:05:00Z",
    "public_url": "https://docs.docuwriter.ai/api-docs"
  },
  "message": "Space created successfully"
}

Response Fields 📦

Field	Type	Description
id	integer	Unique identifier of the Space
name	string	Space name
description	string \	null
is_public	boolean	Visibility flag
slug	string \	null
sort	integer	Sort order for user's Space list
user_id	integer	Owner's user ID
created_at	string	ISO-8601 creation timestamp
public_url	string	Public URL (only included for public Spaces)

---

Slug Auto-Generation

When creating a public Space without an explicit slug:

1. The slug is auto-generated from the name using kebab-case
2. If a collision occurs, a numeric suffix is appended (e.g., my-space-1, my-space-2)

Example:

• Name: "My Awesome Space" → Slug: "my-awesome-space"
• Name: "API Docs" (collision exists) → Slug: "api-docs-1"

---

Error Responses ❌

Status	Condition	Response Body
401	Missing/invalid token	{ "message": "Unauthenticated." }
403	Space quota exceeded	{ "success": false, "message": "You have reached your space limit (N spaces). Please upgrade your plan to create more spaces.", "data": { "current_space_count": N, "plan": "..." } }
422	Validation failed	{ "success": false, "message": "Validation failed", "errors": { "name": ["The name field is required."] } }
422	Duplicate slug	{ "success": false, "message": "Validation failed", "errors": { "slug": ["The slug has already been taken."] } }
500	Server error	{ "success": false, "message": "Failed to create space: <error>" }

Common Validation Errors

• name is required and cannot exceed 250 characters
• slug must be unique across all Spaces
• slug cannot exceed 255 characters

---

API Reference

{
    "title": "Create Space",
    "description": "Create a new Space for organizing documentation",
    "method": "POST",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/spaces",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Accept",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n  \"name\": \"Project Documentation\",\n  \"description\": \"Internal project docs\",\n  \"is_public\": false\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Space created successfully",
            "body": "{\n  \"success\": true,\n  \"data\": {\n    \"id\": 123,\n    \"name\": \"Project Documentation\",\n    \"description\": \"Internal project docs\",\n    \"is_public\": false,\n    \"slug\": null,\n    \"sort\": 5,\n    \"user_id\": 456,\n    \"created_at\": \"2025-09-17T12:00:00Z\"\n  },\n  \"message\": \"Space created successfully\"\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n  \"message\": \"Unauthenticated.\"\n}"
        },
        "403": {
            "description": "Space quota exceeded",
            "body": "{\n  \"success\": false,\n  \"message\": \"You have reached your space limit (1 spaces). Please upgrade your plan to create more spaces.\",\n  \"data\": {\n    \"current_space_count\": 1,\n    \"plan\": \"starter\"\n  }\n}"
        },
        "422": {
            "description": "Validation error",
            "body": "{\n  \"success\": false,\n  \"message\": \"Validation failed\",\n  \"errors\": {\n    \"name\": [\"The name field is required.\"]\n  }\n}"
        },
        "500": {
            "description": "Server error",
            "body": "{\n  \"success\": false,\n  \"message\": \"Failed to create space: Internal error\"\n}"
        }
    }
}