Workspace API

Upsert Favorite View

Favorite or reorder Views with POST /workspace/favorite-views/upsert and /upsert/batch.

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. Favoriting does not copy or fork the View.

Upsert costs 0 credits. Requires a user JWT and workspace membership. API keys receive 400 user_identity_required. 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.

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.