Appearance
Blueprints API
Read the structure of your project's content types: which blueprints exist, what fields they hold, and what shape their values take.
Useful for generating types, validating payloads before you send them, or building tooling that adapts to a project it has not seen before.
List blueprints
GET /v2/blueprintsReturns the blueprints your token can read: those on which it holds view or preview. Others are omitted: a token scoped to blog-posts sees only blog-posts.
json
{
"data": [
{
"id": "blog-posts",
"type": "blueprint",
"attributes": {
"name": "Blog post",
"slug": "blog-posts",
"kind": "resource",
"is_readonly": false,
"is_singular": false,
"record_title": "title",
"variants": ["en", "fr"],
"default_variant": "en",
"fields_count": 6,
"resources_count": 42
}
}
],
"meta": { "total": 1 }
}| Attribute | Description |
|---|---|
kind | resource, singular_resource or readonly_resource (see Blueprints) |
record_title | The field used as the record's display title; absent when none is set |
variants | Variant slugs; absent when the type is not multilingual |
default_variant | Variant used when a request has no variant parameter; absent when none is set |
resources_count | Number of resources, drafts included |
Get one blueprint
GET /v2/blueprints/{blueprint}Adds the field list and a JSON Schema for the type's attributes object.
In fields, required is true when the field's validation rules include required. description and metadata are omitted when not set.
json
{
"data": {
"id": "blog-posts",
"type": "blueprint",
"attributes": { "…": "as above" },
"fields": [
{ "slug": "title", "name": "Title", "type": "text", "required": true },
{ "slug": "category", "name": "Category", "type": "enum", "required": false,
"metadata": { "options": ["news", "tutorial"] } }
],
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": { "type": "string", "title": "Title" },
"category": { "type": "string", "enum": ["news", "tutorial"], "title": "Category" }
}
}
}
}The schema mirrors the field types reference: number and money become number, date carries format: "date", a Choice field becomes an enum, and reference fields describe which type they point at.
Required fields are enforced by the Resources API: a create or PUT that omits one fails with 422 VALIDATION_ERROR. PATCH never requires a field.
Permissions
Both endpoints need view or preview on the blueprint. A token that can read a type's resources can read its schema; one that cannot doesn't see the blueprint in the list and gets 403 on a direct fetch.
| Status | Code | Cause |
|---|---|---|
403 | FORBIDDEN | The token holds neither view nor preview on that blueprint |
404 | RESOURCE_NOT_FOUND | No such blueprint in this project |
A token holding the project-wide blueprint:view or blueprint:manage permission sees every blueprint, whatever its content permissions.
Manage blueprints
Create and change a project's structure from a script or an AI agent. These endpoints need a token with Blueprints › Manage (blueprint:manage), set in Settings › API Tokens. It can be created on a project that has no blueprint yet.
| Status | Code | Cause |
|---|---|---|
403 | FORBIDDEN | The token does not hold blueprint:manage |
422 | VALIDATION_ERROR | Invalid payload; error.details is keyed by path, e.g. blueprints.1.fields.0.type |
Create a blueprint
POST /v2/blueprintsThe body is one blueprint in the JSON import format: name, fields, and optionally slug, icon, type, record_title, variants and data. Returns 201 with the blueprint as Get one blueprint returns it.
bash
curl -X POST https://api.diggama.com/v2/blueprints \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "Articles",
"fields": [
{ "name": "Title", "type": "text", "rules": ["required"] },
{ "name": "Author", "type": "reference", "metadata": { "reference_to": "authors" } }
]
}'Import blueprints
POST /v2/blueprints/importSeveral blueprints at once: the JSON array of the JSON import, or {"blueprints": [...]}. A reference_to may target a blueprint earlier in the same array. All or nothing: if one blueprint is invalid, none is created.
json
{
"data": [ { "id": "authors", "type": "blueprint", "attributes": { "…": "…" } } ],
"meta": { "blueprints_created": 2, "resources_created": 5 }
}A slug that already exists in the project is a 422, never renamed. At most 50 blueprints, 100 fields per blueprint and 1,000 data rows per blueprint per call.
Edit or delete a blueprint
PATCH /v2/blueprints/{blueprint}
DELETE /v2/blueprints/{blueprint}PATCH accepts name, icon and record_title (the slug of one of its fields). The slug and type cannot change. DELETE returns 204 and deletes the blueprint's resources with it.
Fields
POST /v2/blueprints/{blueprint}/fields
PATCH /v2/blueprints/{blueprint}/fields/{field}
DELETE /v2/blueprints/{blueprint}/fields/{field}{field} is the field's slug. POST takes one field in the import format (name, type, and optionally slug, description, rules, metadata; a reference names its target with metadata.reference_to). PATCH accepts name, description, rules and metadata: like in the dashboard, a field's slug and type are fixed once created, since stored values are keyed by the slug. Each call returns the updated blueprint.