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

List Workspaces

Retrieves a list of all workspaces belonging to the authenticated user.

Endpoint

GET /api/v1/workspaces

Authentication

Requires a valid API token in the Authorization header.
Authorization: Bearer dtk_your_token_here

Request

Headers

HeaderValueRequired
AuthorizationBearer tokenYes

Parameters

None

Response

Success Response

Status: 200 OK
{
  "workspaces": [
    {
      "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"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Marketing Site",
      "description": "Marketing website tokens",
      "user_id": "user-123",
      "created_at": "2025-01-10T08:30:00Z",
      "updated_at": "2025-01-14T16:45:00Z"
    }
  ],
  "total": 2
}

Response Fields

FieldTypeDescription
workspacesarrayArray of workspace objects
totalnumberTotal number of workspaces

Workspace Object

FieldTypeDescription
idstringUnique workspace identifier
namestringWorkspace name
descriptionstring|nullOptional description
user_idstringOwner’s user ID
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

Examples

curl -H "Authorization: Bearer dtk_your_token_here" \
  https://app.tokencraft.dev/api/v1/workspaces

Error Responses

401 Unauthorized

{
  "error": "Invalid API token"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Use Cases

1. Initial App Load

Fetch all workspaces when user opens your application:
async function loadWorkspaces() {
  const data = await fetch(url, { headers }).then(r => r.json());
  
  // Display in UI
  renderWorkspaceSelector(data.workspaces);
  
  // Store in state
  store.dispatch(setWorkspaces(data.workspaces));
}

2. Workspace Selector

Build a dropdown menu:
function WorkspaceSelector({ workspaces }) {
  return (
    <select>
      {workspaces.map(ws => (
        <option key={ws.id} value={ws.id}>
          {ws.name}
        </option>
      ))}
    </select>
  );
}

3. Check for Workspaces

Verify user has created workspaces:
const { workspaces, total } = await getWorkspaces();

if (total === 0) {
  showOnboarding('Create your first workspace!');
}

Rate Limiting

This endpoint counts toward your rate limit of 100 requests per minute. See Rate Limits for details.

Next Steps