Get Started
Generate an organization API key, authorize requests, and send your first request to the Blueputto API.
Blueputto exposes a REST API under /v1 for working with items, documents, collections, folders, taxonomies, and document templates. Start here to generate a key, choose an authorization header, and understand the response envelopes used across the API.
The public OpenAPI document keeps request payloads and resource objects flexible for most endpoints. This reference documents the transport layer, authentication, paths, query parameters, and response envelopes without inventing workspace-specific fields.
Base URL
Production requests go to:
https://api.blueputto.comLocal development can use:
http://localhost:3001All routes in this reference start with the /v1 prefix.
Generate an API Key
Open the Developers settings area for the active organization. API keys
are managed from one operational table where your team can search keys, see
when each one was created, review its current rate limit, and rename or
delete credentials later.
Create a new key for the integration you are building. In the current implementation, the creation dialog only asks for a name, which makes it fast to issue a credential for a script, internal tool, or production service.
Copy the key from the post-create dialog immediately. Blueputto reveals the raw secret exactly once and hides it after the dialog is closed.
Store the copied value in a server-side secret manager or environment variable. Keep it out of browser bundles, mobile binaries, public repos, and any other client-side distribution channel.
In the current implementation, new API keys are created without expiration
and start with a default rate limit of 5 req/s.
Authorize Requests
Blueputto accepts either of these headers on every request:
curl https://api.blueputto.com/v1/items \
-H "x-api-key: YOUR_API_KEY"curl https://api.blueputto.com/v1/items \
-H "Authorization: Bearer YOUR_API_KEY"Send Your First Request
The quickest smoke test is a paginated list call:
curl "https://api.blueputto.com/v1/documents?page=1&limit=10" \
-H "x-api-key: YOUR_API_KEY"If the key is valid, the API responds with a JSON object containing a data
array and a meta pagination object.
Response Envelopes
Collection endpoints return this shape:
{
"data": [{}],
"meta": {
"page": 1,
"limit": 10,
"totalItems": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Single-resource endpoints return:
{
"data": {}
}Errors return:
{
"error": {
"code": "string",
"message": "string",
"details": {}
}
}Explore the Reference
Items
CRUD, trash, restore, and permanent deletion for items.
Documents
List, create, duplicate, and manage document lifecycle.
Collections
Create and maintain collections through the public API.
Folders
Read and manage folder structures for document organization.
Categories
Manage categories, including manual reordering.
Statuses
Create, update, delete, and reorder workflow statuses.
Labels
Manage labels and keep their ordering in sync.
Document Templates
Work with document templates and the active-only filter.
Resources
Read supporting material on errors, rate limits, scaling, and security.