Workspace API

The Workspace API lets you read and write your workspace’s own data on top of Parcel’s global accounts. Save the accounts, projects, and contacts you care about, annotate them, manage shared Views (Dynamic filters or Static record lists), and read back Parcel’s computed fields such as Atlas score.

Ordinary entity searches (/workspace/accounts/search, contacts, projects) remain your book — records with a workspace overlay. Broader View execution uses POST /workspace/views/{id}/records/search. See Workspace Views.

Base URL

Base URL

https://api.parcelengineering.com/api/v1

Authentication

All requests require a bearer token:

Authorization header

Authorization: Bearer pcl_your_api_key

API keys can manage shared Views and Static membership. Personal Favorites require a user-authenticated JWT (for example via the MCP OAuth session).

AuthenticationHow to create a workspace API key and keep it secure.

Endpoints

Method	Path	Description
POST	/workspace/accounts/search	Search accounts in your book
GET	/workspace/accounts/{id}	Fetch one workspace account by UUID
POST	/workspace/accounts/upsert	Add or update a workspace account
DELETE	/workspace/accounts/{id}	Remove your workspace’s custom data for an account
GET	/workspace/views	List shared Views
POST	/workspace/views/{id}/records/search	Execute a Dynamic or Static View

Response envelope

Every response wraps its payload in a consistent envelope:

Search response

{
  "data": [ { "id": "8a1f...", "name": "..." } ],
  "metadata": {
    "total": 4,
    "total_is_capped": false,
    "limit": 25,
    "offset": 0,
    "search_after": null,
    "credits": 4
  }
}

Get / upsert / delete response

{
  "data": { "id": "8a1f...", "name": "..." },
  "metadata": { "credits": 1 }
}

• data: the record object, array, or View payload.
• metadata.total: match count for searches, capped at 1,000. When total_is_capped is true, more than 1,000 records match and the true count is unknown.
• metadata.credits: credits consumed by this request. View metadata reads/writes return 0 here.

Note

The Workspace API requires the Pro plan. Requests from non-Pro workspaces or non-members receive a 403. Searching book records or View records costs 1 credit per row returned; fetching one book entity by id costs 1 credit; list/get Views, Favorite operations, upsert, delete, and membership writes cost 0 credits. Credits are an abuse-protection limit included with Pro. See Credits.

Explore the reference

ViewsDynamic and Static Views, definition grammar, Favorites, and follow semantics.DatasetsFields, filters, and sort keys for the accounts you have saved.EndpointsBook CRUD, Views, Favorites, subscriptions, and admin operations.CreditsThe rolling 24-hour credit window, per-operation costs, and how to budget queries.