Public API
Blueputto Public API for authenticated CRUD access to workspace records, with versioned endpoints, API keys, pagination, filters, and workflow actions.
Grzegorz
The Public API is Blueputto's authenticated integration layer. It exposes the same core records the application works with every day, which lets external systems create, read, update, and remove operational data without introducing a second content model beside the UI.
This API lives under /v1 and is designed to work with organization-level API Keys. That makes it the feature teams use when Blueputto data needs to move into a website, automation, import script, internal dashboard, or another product system.
One versioned API for the main workspace resources
The entry point at /v1 returns a compact discovery payload with the API version, authentication format, the OpenAPI document URL, and the list of currently exposed resources.
In the current implementation, the public surface covers:
documents,
items,
collections,
folders,
categories,
statuses,
labels,
and document templates.
Most of those resources support the standard operational path of list, get, create, update, and delete. The API also exposes workflow-specific actions where the UI needs them, such as:
restore and permanent delete for documents and items,
duplicate for documents,
reorder for categories, statuses, and labels,
and active-only filtering for document templates.
That is what makes the Public API more than a read-only export layer. It maps closely to the real record lifecycle already visible in Blueputto itself.
Authentication and response shape stay predictable
The Public API accepts the organization credential in either of two standard forms:
x-api-key,or
Authorization: Bearer <key>.
That gives teams flexibility when wiring Blueputto into different runtimes, gateways, and SDK styles. The key itself is created inside the application from the API Keys settings page.
Response shape is also intentionally consistent. Single-resource responses are returned inside a data envelope. List endpoints return data together with meta, which includes pagination details such as page, limit, total items, total pages, and next or previous page state.
Across the current resource set, the API also exposes practical filters that mirror real UI workflows, including search, deletedOnly, folderId, withoutFolder, and activeOnly.
Built around the same operational rules as the app
The useful part of Blueputto's Public API is not only that records are reachable externally. It is that the integration surface follows the same rules the product already enforces in the UI.
For example, document and item deletion is modeled as a trash-first flow rather than immediate destruction. Some document operations can return a locked-state response when the record is not currently editable. Rate limiting is enforced per API key, with the default backend limit currently set to 5 req/s per key.
That keeps the API aligned with real application behavior. External integrations are working with Blueputto's actual resource model, not with a simplified side channel that behaves differently from the product.
