Upsert Project

Endpoint

POST https://api.parcelengineering.com/api/v1/workspace/projects/upsert

Adds a project to your workspace or updates its custom fields if it is already saved. Projects are identified by UUID only. There is no natural-key match for projects.

Upsert costs 0 credits.

Caution

The Workspace API requires the Pro plan. A request from a non-Pro workspace or a non-member receives 403 forbidden.

Request body

Provide project_id to identify the project. All annotation fields are optional.

Field	Type	Required	Description
project_id	string (UUID)	Yes	The UUID from a Data API project record.
workspace_status	string | null	No	Your workflow state (any string). null clears the value.
notes	string | null	No	Free-text notes. null clears the value.
tags	string[]	No	Full-replace tag set. Sending [] clears all tags.

Partial update semantics

• Omitted fields are left unchanged. You can update workspace_status without touching notes or tags.
• Explicit null clears a field. Sending "notes": null removes the existing note.
• tags is full-replace. Sending "tags": ["seaport"] replaces the entire tag set, not merges it with the existing one.

Example

cURL

Upsert project by id

curl -X POST https://api.parcelengineering.com/api/v1/workspace/projects/upsert \
  -H "Authorization: Bearer pcl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "7b2e4d1f-0001-4c8e-af6b-000000000001",
    "workspace_status": "watching",
    "notes": "GC bid due Q3",
    "tags": ["seaport", "mixed-use"]
  }'

JavaScript

Upsert project by id

const response = await fetch(
  'https://api.parcelengineering.com/api/v1/workspace/projects/upsert',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pcl_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      project_id: '7b2e4d1f-0001-4c8e-af6b-000000000001',
      workspace_status: 'watching',
      notes: 'GC bid due Q3',
      tags: ['seaport', 'mixed-use'],
    }),
  }
);

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

Response

Response

{
  "data": {
    "id": "7b2e4d1f-0001-4c8e-af6b-000000000001",
    "name": "100 Seaport Boulevard",
    "city": "Boston",
    "state": "MA",
    "stage": "under_construction",
    "primary_use": "mixed_use",
    "residential_units": 120,
    "last_signal_at": "2026-06-01T00:00:00Z",
    "workspace_status": "watching",
    "notes": "GC bid due Q3",
    "tags": ["seaport", "mixed-use"]
  },
  "metadata": { "credits": 0 }
}

Upsert costs 0 credits.