Working with Workspaces - Cropwise Core Services

Overview

A Workspace is the top-level container in the Cropwise platform. Every other resource — Organizations, Properties, Fields, Seasons, and Crop Zones — is reached through a Workspace. Permissions granted at the Workspace level apply to every Organization within it.

Core Concepts

What is a Workspace?

A Workspace in Cropwise:

Is the top of the hierarchy — nothing sits above it.
Groups one or more Organizations.
Carries the locale defaults (country, currency, unit_system) inherited by Organizations created in the Workspace.

Workspace Hierarchy

Workspace ← You are here (top — no parent)
└── Organization
    └── Property
        └── Field
            └── Crop Zone

API Endpoints

For complete API reference including request/response schemas, authentication, and interactive examples, please visit:

View Interactive Workspaces API Documentation →

Available Endpoints

POST /v2/workspaces - Create a new Workspace
GET /v2/workspaces - List Workspaces the caller can read (supports case-insensitive name filtering)
GET /v2/workspaces/{id} - Retrieve a Workspace by ID
PATCH /v2/workspaces/{id} - Update editable attributes (name, use_type, country, currency, unit_system, map_satellite_layer_provider, metadata)
DELETE /v2/workspaces/{id} - Delete a Workspace

Additional v2 Endpoints

POST /v2/workspaces/ids - Batch fetch by ID list

v2 Sub-resource Endpoints

The same surface anchors a scoped collection pointing at a documented entity:

GET /v2/workspaces/{id}/orgs - Organizations within the Workspace

Discovery Endpoint

GET /v2/accounts/workspaces - List the Workspaces the current authenticated user can access. Typical entry point after login.

Workspace Attributes

Attribute	Rule / Constraint
`name`	Required. Non-empty string, up to 255 characters
`use_type`	Optional. Categorical label for the kind of customer (`SYNGENTA_DIGITAL_GROWER`, `SYNGENTA_DIGITAL_DISTRIBUTION`, `DEMO`, `OPEN_PLATFORM`, ...)
`country`	Optional. Default inherited by Organizations created in the Workspace
`currency`	Optional. Default inherited by Organizations created in the Workspace
`unit_system`	Optional. Default inherited by Organizations created in the Workspace
`map_satellite_layer_provider`	Optional. `mapbox` or `googlemaps`. Defaults to `mapbox`
`metadata`	Optional JSON object — free-form bag for non-structured attributes

Best Practices

Use /v2/accounts/workspaces as the entry point after login. It filters by the caller's access; listing all Workspaces with GET /v2/workspaces requires a system-level grant.
Workspaces are typically not created by end users. A personal Workspace is created automatically at signup; additional Workspaces are usually created by administrators or privileged services.

Next Steps

After provisioning your Workspace, you can: