API Endpoints

This page documents the REST API endpoints for Room Design operations. All endpoints support full CRUD operations and follow RESTful conventions.

Base URL

https://api.rdesign.example.com/v0/project/room_designs

All API requests require authentication via Bearer token. Include your API key in the Authorization header.

Authentication

Header Format

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Error Responses

Status Code	Meaning
`401`	Unauthorized - Invalid or missing token
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`422`	Unprocessable Entity - Validation error
`500`	Internal Server Error

Room Design Endpoints

List Room Designs

Retrieve a paginated list of room designs accessible to the authenticated user.

Endpoint: GET /v0/project/room_designs

Query Parameters:

Parameter	Type	Default	Description
`page`	Integer	1	Page number
`per_page`	Integer	20	Items per page (max: 100)
`type`	String	-	Filter by design type: `app`, `streaming`, `floorplan`
`visibility`	String	-	Filter by visibility: `opened`, `hidden`, `limited`, `closed`
`owner_id`	UUID	-	Filter by owner
`sort`	String	`updated_at`	Sort field: `created_at`, `updated_at`, `name`
`order`	String	`desc`	Sort order: `asc`, `desc`
`search`	String	-	Search in name and description

Example Request:

curl -X GET "https://api.rdesign.example.com/v0/project/room_designs?page=1&per_page=20&type=app" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response:

{
  "data": [
    {
      "id": "uuid-123",
      "name": "Modern Living Room",
      "type": "app",
      "visibility": "limited",
      "owner_id": "uuid-user-456",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z",
      "version": 3,
      "thumbnail_url": "https://cdn.example.com/thumb-123.jpg",
      "bom_count": 24,
      "total_value": 15420.50,
      "currency": "USD"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_pages": 5,
    "total_count": 94
  }
}

Get Room Design

Retrieve detailed information about a specific room design.

Endpoint: GET /v0/project/room_designs/:id

Path Parameters:

Parameter	Type	Description
`id`	UUID	Room design identifier

Query Parameters:

Parameter	Type	Default	Description
`include`	String	-	Include related data: `bom`, `cameras`, `media`, `permissions`

Example Request:

curl -X GET "https://api.rdesign.example.com/v0/project/room_designs/uuid-123?include=bom,cameras" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response:

{
  "id": "uuid-123",
  "name": "Modern Living Room",
  "type": "app",
  "visibility": "limited",
  "owner_id": "uuid-user-456",
  "description": "Contemporary design with minimalist aesthetic",
  "tags": ["modern", "minimalist", "living-room"],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z",
  "version": 3,
  "thumbnail_url": "https://cdn.example.com/thumb-123.jpg",
  "bom": [
    {
      "id": "uuid-bom-1",
      "product_id": "uuid-prod-789",
      "quantity": 1,
      "position": {"x": 0, "y": 0, "z": 0},
      "rotation": {"x": 0, "y": 90, "z": 0},
      "scale": {"x": 1, "y": 1, "z": 1},
      "price": 899.99,
      "currency": "USD"
    }
  ],
  "cameras": [
    {
      "id": "uuid-cam-1",
      "name": "Main View",
      "position": {"x": 5, "y": 1.6, "z": 5},
      "target": {"x": 0, "y": 1, "z": 0},
      "fov": 60,
      "is_default": true
    }
  ],
  "permissions": {
    "can_edit": true,
    "can_delete": true,
    "can_share": true,
    "can_transfer": false
  }
}

Create Room Design

Create a new room design.

Endpoint: POST /v0/project/room_designs

Request Body:

{
  "room_design": {
    "name": "New Living Room",
    "type": "app",
    "visibility": "closed",
    "description": "Initial design concept",
    "tags": ["modern", "living-room"]
  }
}

Required Fields:

name (String, 1-200 characters)
type (Enum: app, streaming, floorplan)

Optional Fields:

visibility (Enum: opened, hidden, limited, closed, default: closed)
description (Text, max 2000 characters)
tags (Array of strings, max 10 tags)

Example Request:

curl -X POST "https://api.rdesign.example.com/v0/project/room_designs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "room_design": {
      "name": "New Living Room",
      "type": "app",
      "visibility": "closed"
    }
  }'

Example Response:

{
  "id": "uuid-new-123",
  "name": "New Living Room",
  "type": "app",
  "visibility": "closed",
  "owner_id": "uuid-user-456",
  "created_at": "2024-01-25T09:00:00Z",
  "updated_at": "2024-01-25T09:00:00Z",
  "version": 1
}

Status Code: 201 Created - Room design successfully created

Update Room Design

Update an existing room design’s metadata.

Endpoint: PATCH /v0/project/room_designs/:id

Permission Required: Owner, Admin, or Collaborator (for opened/limited designs)

Request Body:

{
  "room_design": {
    "name": "Updated Living Room Name",
    "visibility": "limited",
    "description": "Updated description",
    "tags": ["modern", "scandinavian"]
  }
}

Example Request:

curl -X PATCH "https://api.rdesign.example.com/v0/project/room_designs/uuid-123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "room_design": {
      "visibility": "opened"
    }
  }'

Example Response:

{
  "id": "uuid-123",
  "name": "Updated Living Room Name",
  "visibility": "opened",
  "updated_at": "2024-01-25T10:30:00Z",
  "version": 4
}

⚠️

Updates increment the version number. Major changes may trigger automatic thumbnail regeneration.

Delete Room Design

Permanently delete a room design.

Endpoint: DELETE /v0/project/room_designs/:id

Permission Required: Owner or Admin

Example Request:

curl -X DELETE "https://api.rdesign.example.com/v0/project/room_designs/uuid-123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response:

{
  "message": "Room design successfully deleted",
  "deleted_at": "2024-01-25T11:00:00Z"
}

🚫

Warning: Deletion is permanent after 30 days. Deleted designs can be restored within this period by contacting support.

List Collaborators

Get all users who have access to a room design.

Endpoint: GET /v0/project/room_designs/:id/collaborators

Example Response:

{
  "collaborators": [
    {
      "user_id": "uuid-user-456",
      "email": "owner@example.com",
      "name": "John Doe",
      "permission": "owner",
      "added_at": "2024-01-15T10:30:00Z"
    },
    {
      "user_id": "uuid-user-789",
      "email": "designer@example.com",
      "name": "Jane Smith",
      "permission": "collaborator",
      "added_at": "2024-01-18T14:20:00Z",
      "added_by": "uuid-user-456"
    }
  ]
}

Add Collaborator

Grant access to a user.

Endpoint: POST /v0/project/room_designs/:id/collaborators

Permission Required: Owner or Admin

Request Body:

{
  "collaborator": {
    "user_id": "uuid-user-999",
    "permission": "collaborator"
  }
}

Permission Levels:

admin - Full control except ownership transfer
collaborator - Can edit opened/limited designs
viewer - Read-only access

Example Request:

curl -X POST "https://api.rdesign.example.com/v0/project/room_designs/uuid-123/collaborators" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collaborator": {
      "user_id": "uuid-user-999",
      "permission": "viewer"
    }
  }'

Update Collaborator Permission

Change a user’s permission level.

Endpoint: PATCH /v0/project/room_designs/:id/collaborators/:user_id

Request Body:

{
  "collaborator": {
    "permission": "admin"
  }
}

Remove Collaborator

Revoke a user’s access.

Endpoint: DELETE /v0/project/room_designs/:id/collaborators/:user_id

Permission Required: Owner or Admin

curl -X DELETE "https://api.rdesign.example.com/v0/project/room_designs/uuid-123/collaborators/uuid-user-999" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Transfer Ownership

Transfer ownership to another user.

Endpoint: POST /v0/project/room_designs/:id/transfer_ownership

Permission Required: Owner only

Request Body:

{
  "new_owner_id": "uuid-user-999"
}

🚫

Critical: Ownership transfer is irreversible. The original owner becomes an Admin after transfer.

BOM (Bill of Materials) Endpoints

Get BOM

Retrieve all products in a room design.

Endpoint: GET /v0/project/room_designs/:id/bom

Example Response:

{
  "bom_entries": [
    {
      "id": "uuid-bom-1",
      "product_id": "uuid-prod-789",
      "product_name": "Modern Sofa",
      "manufacturer": "Design Co.",
      "quantity": 1,
      "position": {"x": 0, "y": 0, "z": 0},
      "rotation": {"x": 0, "y": 90, "z": 0},
      "scale": {"x": 1, "y": 1, "z": 1},
      "price": 899.99,
      "currency": "USD",
      "configuration": {
        "fabric": "leather-brown",
        "legs": "wooden"
      }
    }
  ],
  "summary": {
    "total_items": 24,
    "total_value": 15420.50,
    "currency": "USD"
  }
}

Add Product to BOM

Place a product in the room.

Endpoint: POST /v0/project/room_designs/:id/bom

Request Body:

{
  "bom_entry": {
    "product_id": "uuid-prod-789",
    "quantity": 1,
    "position": {"x": 2.5, "y": 0, "z": -1.0},
    "rotation": {"x": 0, "y": 45, "z": 0},
    "configuration": {
      "fabric": "fabric-blue"
    }
  }
}

Update BOM Entry

Modify a product’s placement or configuration.

Endpoint: PATCH /v0/project/room_designs/:id/bom/:bom_entry_id

Delete BOM Entry

Remove a product from the room.

Endpoint: DELETE /v0/project/room_designs/:id/bom/:bom_entry_id

Media & Rendering Endpoints

List Media Assets

Get all images, videos, and VR tours.

Endpoint: GET /v0/project/room_designs/:id/media

Query Parameters:

Parameter	Type	Description
`type`	String	Filter by: `image`, `video`, `vr_tour`, `thumbnail`

Upload Media

Upload a rendered image or video.

Endpoint: POST /v0/project/room_designs/:id/media

Content-Type: multipart/form-data

Form Fields:

file (required) - The media file
type (required) - Media type: image, video, thumbnail
camera_id (optional) - Associated camera
render_settings (optional) - JSON of render settings

Request Render

Trigger a server-side render.

Endpoint: POST /v0/project/room_designs/:id/render

Request Body:

{
  "render": {
    "type": "image",
    "camera_id": "uuid-cam-1",
    "resolution": "1920x1080",
    "quality": "high",
    "format": "png"
  }
}

Response:

{
  "job_id": "uuid-job-123",
  "status": "queued",
  "estimated_time": 120
}

Get Render Status

Check render progress.

Endpoint: GET /v0/project/room_designs/:id/render/:job_id

Product Integration Endpoints

Search Products

Search the product catalog.

Endpoint: GET /v0/products

Query Parameters:

Parameter	Type	Description
`q`	String	Search query
`category`	String	Product category
`manufacturer`	String	Brand filter
`min_price`	Decimal	Minimum price
`max_price`	Decimal	Maximum price

Get Product Details

Endpoint: GET /v0/products/:product_id

Example Response:

{
  "id": "uuid-prod-789",
  "name": "Modern Sofa",
  "manufacturer": "Design Co.",
  "model_number": "DS-3000",
  "category": "seating",
  "price": 899.99,
  "currency": "USD",
  "availability": "in_stock",
  "3d_model_url": "https://cdn.example.com/models/sofa-3000.glb",
  "thumbnail_url": "https://cdn.example.com/products/sofa-thumb.jpg",
  "specifications": {
    "width": 200,
    "height": 85,
    "depth": 90,
    "unit": "cm"
  },
  "configurable_options": [
    {
      "name": "fabric",
      "type": "material",
      "options": ["leather-brown", "fabric-blue", "fabric-gray"]
    }
  ]
}

Streaming Endpoints

Create Streaming Session

Start a streaming session for remote viewing.

Endpoint: POST /v0/project/room_designs/:id/streaming/sessions

Request Body:

{
  "session": {
    "duration_minutes": 60,
    "allow_viewer_control": true,
    "quality": "high"
  }
}

Response:

{
  "session_id": "uuid-session-123",
  "streaming_url": "https://stream.example.com/session-123",
  "expires_at": "2024-01-25T15:00:00Z",
  "viewer_url": "https://view.example.com/session-123"
}

End Streaming Session

Endpoint: DELETE /v0/project/room_designs/:id/streaming/sessions/:session_id

Rate Limits

Tier	Requests/Hour	Burst
Free	100	10/min
Pro	1,000	100/min
Enterprise	10,000	1,000/min

⚠️

Rate limit headers are included in all responses:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Webhooks

Subscribe to events for real-time updates:

room_design.created
room_design.updated
room_design.deleted
render.completed
collaborator.added
collaborator.removed

Configure webhooks in your account settings.

SDKs & Libraries

Official SDKs available for:

JavaScript/TypeScript
Python
Ruby
PHP
C# / .NET

Next Steps

Learn about the Data Model for detailed schema information
Review Permissions & Visibility for access control
Return to Overview for conceptual information

Data Model Design Family

API Endpoints

Base URL

Authentication

Header Format

Error Responses

Room Design Endpoints

List Room Designs

Get Room Design

Create Room Design

Update Room Design

Delete Room Design

Sharing & Collaboration Endpoints

List Collaborators

Add Collaborator

Update Collaborator Permission

Remove Collaborator

Transfer Ownership

BOM (Bill of Materials) Endpoints

Get BOM

Add Product to BOM

Update BOM Entry

Delete BOM Entry

Media & Rendering Endpoints

List Media Assets

Upload Media

Request Render

Get Render Status

Product Integration Endpoints

Search Products

Get Product Details

Streaming Endpoints

Create Streaming Session

End Streaming Session

Rate Limits

Webhooks

SDKs & Libraries

Next Steps