Skip to content

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/blueprints

Returns 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 }
}
AttributeDescription
kindresource, singular_resource or readonly_resource (see Blueprints)
record_titleThe field used as the record's display title; absent when none is set
variantsVariant slugs; absent when the type is not multilingual
default_variantVariant used when a request has no variant parameter; absent when none is set
resources_countNumber 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.

StatusCodeCause
403FORBIDDENThe token holds neither view nor preview on that blueprint
404RESOURCE_NOT_FOUNDNo 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.

StatusCodeCause
403FORBIDDENThe token does not hold blueprint:manage
422VALIDATION_ERRORInvalid payload; error.details is keyed by path, e.g. blueprints.1.fields.0.type

Create a blueprint ​

POST /v2/blueprints

The 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/import

Several 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.

Diggama Documentation