Core concepts
Understand organizations, resource relationships, lifecycle operations, and response patterns in the Blueputto API.
The Blueputto API works with the records inside one organization. This page explains how those records relate to each other so you can choose the right endpoint and safely model a sync or import.
Organization scope
Every API key belongs to one organization. The key determines which data a request can read or change, so requests do not include an organization ID in the URL or a separate organization header. Use a different key for each organization or integration that needs independent access.
Resource IDs
Resources are identified by UUIDs. List or create a resource to obtain its ID,
then use that value in a route such as /v1/objects/{objectId} or in a request
body such as collectionId.
Main resources
| Resource | Use it for | Important relationships |
|---|---|---|
| Objects | Collection records and their structured metadata. | An object belongs to a collection and is created with a design. It can be connected to categories, data models, documents, and a status. |
| Documents | Editorial records, reports, and other document content. | A document may belong to a folder, be created from a template, and be linked to objects and labels. |
| Collections | Groups of objects. | Collections can be limited to teams and optionally made publicly visible. |
| Folders | Organization of documents. | Folders can be limited to teams. A document can have no folder. |
| Categories | Classification for objects. | Category assignments are set through an object's categoryIds. |
| Statuses | Operational state for objects. | An object's statusId refers to a status; statuses are separated by type. |
| Labels | Tags for documents and templates. | Document and template requests use labelIds. |
| Templates | Reusable starting points for documents. | A template can provide document content, labels, and author information when a document is created from it. |
The public API currently exposes these eight resource groups. Designs, data
models, media, signing, and account settings are used by some of these records
but do not have public /v1 endpoints.
Custom fields and content
Objects and documents can contain workspace-specific structured data. Those values are intentionally not fixed to one global schema:
- object
fields,metadata, anddataModelValuesare JSON objects; - document
fieldsis a JSON object, whilecontentandmetadataare JSON arrays; and - the data-model configuration in your organization determines how custom field values are interpreted.
The endpoint pages document the supported top-level request fields. Preserve the shape of custom values already returned by your workspace unless you know the corresponding data-model definition.
Lifecycle operations
Objects and documents use a two-stage deletion flow. DELETE moves the record
to Trash; list it later with deletedOnly=true, restore it with /restore, or
remove it irreversibly with /permanent.
Documents that are no longer drafts are restricted for signing. Changes to a
document's title, folder, author, content, content format, labels, or visit ID
return 423 Locked; its metadata, custom fields, and linked objects may still
be updated. Moving a non-draft document to Trash also returns 423 Locked.
Deleting a folder can return 423 Locked if it contains a document locked for
signing.
Collections, folders, categories, statuses, labels, and templates are deleted
directly by their DELETE endpoints.
Pagination and envelopes
List endpoints return a data array and pagination metadata. Single-resource
and mutation endpoints return their result in data. See Get Started
for the exact response envelopes and Rate Limits
for integration guidance.