Workspace API

Favorite Views

List, favorite, reorder, and unfavorite Views for the current user with GET/POST/DELETE /workspace/favorite-views.

Every route below costs 0 credits and requires a user JWT and workspace membership. API keys receive 400 user_identity_required on all three — Favorites are personal state and have no API-key principal to attach to.

Favoriting never copies or forks the shared View; it only stores a personal pointer (and, for Upsert, a personal position). See Workspace Views.

List Favorite Views

GET https://api.parcelengineering.com/api/v1/workspace/favorite-views

Returns the authenticated user’s Favorites in personal order, with each View’s shared definition and metadata.

Query parameters

Parameter	Type	Required	Description
`workspace_id`	string (UUID)	Yes (JWT)	Attribution for the user session.
`limit`	integer 1..100	No	Default `25`.
`offset`	integer ≥ 0	No	Default `0`.

curl "https://api.parcelengineering.com/api/v1/workspace/favorite-views?workspace_id=w1e2f3a4-0001-4b7c-9e5d-000000000001" \
  -H "Authorization: Bearer eyJhbGciOi..."

const response = await fetch(
  'https://api.parcelengineering.com/api/v1/workspace/favorite-views?workspace_id=w1e2f3a4-0001-4b7c-9e5d-000000000001',
  {
    headers: { 'Authorization': 'Bearer eyJhbGciOi...' },
  }
);

const { data, metadata } = await response.json();

Response

{
  "data": {
    "views": [
      {
        "id": "a1b2c3d4-0001-4e8d-bf6a-000000000001",
        "workspace_id": "w1e2f3a4-0001-4b7c-9e5d-000000000001",
        "dataset": "account",
        "view_type": "dynamic",
        "name": "Tier 1 architects",
        "definition": {
          "version": 1,
          "q": "",
          "fields": { "icp_tier": ["tier_1"] }
        },
        "presentation": {
          "version": 1,
          "sorting": [],
          "column_visibility": {}
        },
        "revision": 1,
        "created_by": "d1e2f3a4-0001-4b7c-9e5d-000000000001",
        "updated_by": "d1e2f3a4-0001-4b7c-9e5d-000000000001",
        "created_at": "2026-07-01T12:00:00.000Z",
        "updated_at": "2026-07-01T12:00:00.000Z",
        "is_favorite": true,
        "favorite_position": 0
      }
    ]
  },
  "metadata": { "limit": 25, "offset": 0, "credits": 0 }
}

Favoriting does not copy the View. Renaming the shared View updates every Favorite automatically.

Upsert Favorite View

POST https://api.parcelengineering.com/api/v1/workspace/favorite-views/upsert
POST https://api.parcelengineering.com/api/v1/workspace/favorite-views/upsert/batch

Favorites a shared View for the current user, or updates its personal position. Batch upsert is how you reorder Favorites.

The server never accepts an arbitrary user_id.

Request body

Single:

Field	Type	Required	Description
`view_id`	string (UUID)	Yes	Shared View in this workspace.
`position`	integer ≥ 0	No	Dense personal order. Omitted appends or keeps existing position per service rules.

Batch:

{
  "inputs": [
    { "view_id": "a1b2c3d4-0001-4e8d-bf6a-000000000001", "position": 0 },
    { "view_id": "b2c3d4e5-0002-4e8d-bf6a-000000000002", "position": 1 }
  ]
}

1–100 inputs. Per-item results in input order; for multiple position writes to the same View, the last successful input wins.

Example

cURL
JavaScript

curl -X POST https://api.parcelengineering.com/api/v1/workspace/favorite-views/upsert \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "view_id": "a1b2c3d4-0001-4e8d-bf6a-000000000001",
    "position": 0
  }'

const response = await fetch(
  'https://api.parcelengineering.com/api/v1/workspace/favorite-views/upsert',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer eyJhbGciOi...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      view_id: 'a1b2c3d4-0001-4e8d-bf6a-000000000001',
      position: 0,
    }),
  }
);

const { data, metadata } = await response.json();

Response

{
  "data": {
    "view": {
      "id": "a1b2c3d4-0001-4e8d-bf6a-000000000001",
      "workspace_id": "w1e2f3a4-0001-4b7c-9e5d-000000000001",
      "dataset": "account",
      "view_type": "static",
      "name": "Architects to follow",
      "definition": { "version": 1 },
      "presentation": {
        "version": 1,
        "sorting": [],
        "column_visibility": {}
      },
      "revision": 1,
      "created_by": null,
      "updated_by": null,
      "created_at": "2026-07-01T12:00:00.000Z",
      "updated_at": "2026-07-01T12:00:00.000Z",
      "is_favorite": true,
      "favorite_position": 0
    }
  },
  "metadata": { "credits": 0 }
}

Unknown Views return 404 view_not_found.

Delete a Favorite View

DELETE https://api.parcelengineering.com/api/v1/workspace/favorite-views/{viewId}
POST https://api.parcelengineering.com/api/v1/workspace/favorite-views/delete/batch

Removes the current user’s Favorite pointer. The shared View is unchanged. Unfavorite is idempotent for the single route when the Favorite is already absent.

Path parameters (single)

Parameter	Description
`viewId`	UUID of the shared View to unfavorite.

Batch body

{ "ids": ["a1b2c3d4-0001-4e8d-bf6a-000000000001", "b2c3d4e5-0002-4e8d-bf6a-000000000002"] }

1–100 View UUIDs. Per-item results in input order.

Example

cURL
JavaScript

curl -X DELETE \
  https://api.parcelengineering.com/api/v1/workspace/favorite-views/a1b2c3d4-0001-4e8d-bf6a-000000000001 \
  -H "Authorization: Bearer eyJhbGciOi..."

const response = await fetch(
  'https://api.parcelengineering.com/api/v1/workspace/favorite-views/a1b2c3d4-0001-4e8d-bf6a-000000000001',
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer eyJhbGciOi...' },
  }
);

const { data, metadata } = await response.json();

Response

{
  "data": { "deleted": true },
  "metadata": { "credits": 0 }
}