# Workspaces

Workspaces are separate areas of your organization. Each has its own campaigns, accounts and contacts.

Base URL: https://api.melioralab.io/v1. Pass the key in the `Authorization: Bearer mel_live_...` header.

Endpoints:

- `GET /v1/workspaces`: List workspaces

## The Workspace object

Workspace: a separate area of the organization with its own campaigns.

| Field | Type | Description |
|---|---|---|
| `object` | string | Object type, always `workspace`. |
| `id` | string (uuid) | Workspace ID. |
| `name` | string | Workspace name. |
| `created_at` | string (date-time) or null | When the workspace was created. Can be `null` for older workspaces. |

Example:

```json
{
  "object": "workspace",
  "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
  "name": "Main workspace",
  "created_at": "2026-09-01T12:00:00.000Z"
}
```

## List workspaces

`GET /v1/workspaces`

Workspaces in the key's scope, oldest first. Available to a key with any set of permissions.

Permission: any read permission. Request weight: 1.

### Parameters

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer | no | Number of objects to return per page. From 1 to 100. Defaults to `50`. |
| `cursor` | query | string | no | The `next_cursor` value from the previous response. Other filters must match the first request. |

### Response

A list: `object`, `data`, `has_more`, `next_cursor`. Pagination: https://docs.melioralab.io/en/md/pagination.md

### Endpoint-specific errors

- `cursor_mismatch` (400): The cursor is corrupted, was issued for a different route or filters, or the key's permissions and scope have changed.
- `scope_required` (403): The key does not have permission for this read. Texts also require "Message text" to be enabled.
- `not_found` (404): The object was not found or is outside the key's scope. An unknown path also returns 404.
- `cursor_expired` (410): The cursor expired: 15 minutes for lists, 30 days for the event feed.

Common errors: https://docs.melioralab.io/en/md/errors.md

### Example request

```bash
curl https://api.melioralab.io/v1/workspaces \
  -H "Authorization: Bearer $MELIORA_API_KEY"
```

### Example response

```json
{
  "object": "list",
  "data": [
    {
      "object": "workspace",
      "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
      "name": "Main workspace",
      "created_at": "2026-09-01T12:00:00.000Z"
    },
    {
      "object": "workspace",
      "id": "7a2c5e81-3d9f-4b6a-8c40-1e5f7a9b2d68",
      "name": "Test outreach",
      "created_at": "2026-10-02T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```