Structure Templates¶

Structure templates define content schemas for Creation Mode (mode: "creation"). They tell the AI what kind of content to generate -- product descriptions, category texts, meta tags, and more.

Templates come in three scopes:

Scope	Description	Editable
system	Built-in templates maintained by Falara	Read-only
private	Bound to a single API key	Yes
account	Shared across all API keys in an account	Yes

List Templates¶

GET /v1/structure-templates

List all templates accessible to the current API key. This includes system templates, private templates owned by the key, and account-scoped templates.

Authentication: X-API-Key header Status: 200 OK

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/structure-templates \
  -H "X-API-Key: YOUR_API_KEY"

import requests

resp = requests.get(
    "https://app.falara.io/v1/structure-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
templates = resp.json()

const resp = await fetch(
  "https://app.falara.io/v1/structure-templates",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const templates = await resp.json();

Response 200 OK

[
  {
    "id": "tpl_abc123",
    "slug": "product-description",
    "name": "Product Description",
    "description": "E-commerce product description with title, body, and meta",
    "scope": "system",
    "fields": [
      { "key": "title", "label": "Product Title", "type": "text", "max_length": 80 },
      { "key": "description", "label": "Description", "type": "textarea", "max_length": 2000 }
    ],
    "created_at": "2026-01-10T08:00:00Z"
  }
]

Get a Template¶

GET /v1/structure-templates/{template_id}

Retrieve a single template by its ID or slug.

Authentication: X-API-Key header Status: 200 OK

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/structure-templates/product-description \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.get(
    "https://app.falara.io/v1/structure-templates/product-description",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
template = resp.json()

const resp = await fetch(
  "https://app.falara.io/v1/structure-templates/product-description",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const template = await resp.json();

Response 200 OK

{
  "id": "tpl_abc123",
  "slug": "product-description",
  "name": "Product Description",
  "description": "E-commerce product description with title, body, and meta",
  "scope": "system",
  "fields": [
    { "key": "title", "label": "Product Title", "type": "text", "max_length": 80 },
    { "key": "description", "label": "Description", "type": "textarea", "max_length": 2000 },
    { "key": "meta_title", "label": "Meta Title", "type": "text", "max_length": 60 },
    { "key": "meta_description", "label": "Meta Description", "type": "text", "max_length": 160 }
  ],
  "created_at": "2026-01-10T08:00:00Z"
}

Field Object Schema

Property	Type	Description
`key`	string	Unique field identifier within the template
`label`	string	Human-readable field label
`type`	string	Field type: `"text"`, `"textarea"`, `"number"`, `"boolean"`
`max_length`	integer	Maximum character count (for text fields)

Create a Template¶

POST /v1/structure-templates

Create a new private or account-scoped template.

Authentication: X-API-Key header Status: 201 Created

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/structure-templates \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blog Post",
    "description": "SEO-optimized blog post with headline, body, and meta tags",
    "scope": "private",
    "fields": [
      { "key": "headline", "label": "Headline", "type": "text", "max_length": 100 },
      { "key": "body", "label": "Body Text", "type": "textarea", "max_length": 5000 },
      { "key": "meta_title", "label": "Meta Title", "type": "text", "max_length": 60 },
      { "key": "meta_description", "label": "Meta Description", "type": "text", "max_length": 160 }
    ]
  }'

resp = requests.post(
    "https://app.falara.io/v1/structure-templates",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "Blog Post",
        "description": "SEO-optimized blog post with headline, body, and meta tags",
        "scope": "private",
        "fields": [
            {"key": "headline", "label": "Headline", "type": "text", "max_length": 100},
            {"key": "body", "label": "Body Text", "type": "textarea", "max_length": 5000},
            {"key": "meta_title", "label": "Meta Title", "type": "text", "max_length": 60},
            {"key": "meta_description", "label": "Meta Description", "type": "text", "max_length": 160},
        ],
    },
)
template = resp.json()

const resp = await fetch("https://app.falara.io/v1/structure-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Blog Post",
    description: "SEO-optimized blog post with headline, body, and meta tags",
    scope: "private",
    fields: [
      { key: "headline", label: "Headline", type: "text", max_length: 100 },
      { key: "body", label: "Body Text", type: "textarea", max_length: 5000 },
      { key: "meta_title", label: "Meta Title", type: "text", max_length: 60 },
      { key: "meta_description", label: "Meta Description", type: "text", max_length: 160 },
    ],
  }),
});
const template = await resp.json();

Request Body

Field	Type	Required	Description
`name`	string	yes	Template name
`description`	string	no	Optional description
`scope`	string	no	`"private"` (default) or `"account"`
`fields`	list	yes	Field definitions (see Field Object Schema above)

Field Limits

Each template supports up to 50 fields. The maximum number of templates is 50 per private scope and 50 per account scope.

Create Template from File¶

POST /v1/structure-templates/from-file

Upload a document and let Falara analyze its structure to produce a template draft. Supported file types: DOCX, PDF, HTML, and Markdown.

Authentication: X-API-Key header Content-Type: multipart/form-data Status: 201 Created

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/structure-templates/from-file \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@product_page.docx" \
  -F 'context_json={"source_type": "own_document", "description": "Standard product page layout"}'

import json

with open("product_page.docx", "rb") as f:
    resp = requests.post(
        "https://app.falara.io/v1/structure-templates/from-file",
        headers={"X-API-Key": "YOUR_API_KEY"},
        files={"file": ("product_page.docx", f, "application/vnd.openxmlformats-officedocument.wordprocessingml.document")},
        data={
            "context_json": json.dumps({
                "source_type": "own_document",
                "description": "Standard product page layout",
            })
        },
    )
draft = resp.json()

const formData = new FormData();
formData.append("file", fileBlob, "product_page.docx");
formData.append(
  "context_json",
  JSON.stringify({
    source_type: "own_document",
    description: "Standard product page layout",
  })
);

const resp = await fetch(
  "https://app.falara.io/v1/structure-templates/from-file",
  {
    method: "POST",
    headers: { "X-API-Key": "YOUR_API_KEY" },
    body: formData,
  }
);
const draft = await resp.json();

Form Fields

Field	Type	Required	Description
`file`	file	yes	Document to analyze (DOCX, PDF, HTML, or MD)
`context_json`	string (JSON)	no	Additional context as JSON: `source_type` (`"own_document"` or `"reference"`) and `description`

Review the Draft

The generated template is a best-effort draft based on document analysis. Review and adjust the fields before using it in production jobs.

Delete a Template¶

DELETE /v1/structure-templates/{template_id}

Delete a private or account-scoped template.

Authentication: X-API-Key header Status: 204 No Content

cURLPythonJavaScript

curl -X DELETE https://app.falara.io/v1/structure-templates/tpl_xyz789 \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.delete(
    "https://app.falara.io/v1/structure-templates/tpl_xyz789",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
assert resp.status_code == 204

await fetch(
  "https://app.falara.io/v1/structure-templates/tpl_xyz789",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);

System Templates

System templates cannot be deleted. Attempting to delete a system template returns 403 Forbidden.

CSV Mappings¶

CSV mappings define how columns in a CSV file map to template fields. Use them with POST /v1/jobs/batch-csv to bulk-create content from spreadsheet exports.

Create a CSV Mapping¶

POST /v1/csv-mappings

Authentication: X-API-Key header Status: 201 Created

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/csv-mappings \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shop Export Mapping",
    "column_map": {
      "Produktname": "title",
      "Beschreibung": "description",
      "SEO-Titel": "meta_title"
    },
    "delimiter": ";",
    "encoding": "utf-8",
    "skip_header": true
  }'

resp = requests.post(
    "https://app.falara.io/v1/csv-mappings",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "Shop Export Mapping",
        "column_map": {
            "Produktname": "title",
            "Beschreibung": "description",
            "SEO-Titel": "meta_title",
        },
        "delimiter": ";",
        "encoding": "utf-8",
        "skip_header": True,
    },
)
mapping = resp.json()

const resp = await fetch("https://app.falara.io/v1/csv-mappings", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Shop Export Mapping",
    column_map: {
      Produktname: "title",
      Beschreibung: "description",
      "SEO-Titel": "meta_title",
    },
    delimiter: ";",
    encoding: "utf-8",
    skip_header: true,
  }),
});
const mapping = await resp.json();

Request Body

Field	Type	Required	Description
`name`	string	yes	Human-readable mapping name
`column_map`	object	yes	Maps CSV column headers to template field keys
`delimiter`	string	no	Column delimiter (default: `","`)
`encoding`	string	no	File encoding (default: `"utf-8"`)
`skip_header`	boolean	no	Whether the first row is a header (default: `true`)

List CSV Mappings¶

GET /v1/csv-mappings

Retrieve all CSV mappings for the current API key.

Authentication: X-API-Key header Status: 200 OK

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/csv-mappings \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.get(
    "https://app.falara.io/v1/csv-mappings",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
mappings = resp.json()

const resp = await fetch("https://app.falara.io/v1/csv-mappings", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const mappings = await resp.json();

Get a CSV Mapping¶

GET /v1/csv-mappings/{mapping_id}

Retrieve a single CSV mapping by ID.

Authentication: X-API-Key header Status: 200 OK

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/csv-mappings/cmap_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.get(
    "https://app.falara.io/v1/csv-mappings/cmap_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
mapping = resp.json()

const resp = await fetch(
  "https://app.falara.io/v1/csv-mappings/cmap_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const mapping = await resp.json();

Delete a CSV Mapping¶

DELETE /v1/csv-mappings/{mapping_id}

Delete a CSV mapping.

Authentication: X-API-Key header Status: 204 No Content

cURLPythonJavaScript

curl -X DELETE https://app.falara.io/v1/csv-mappings/cmap_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.delete(
    "https://app.falara.io/v1/csv-mappings/cmap_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
assert resp.status_code == 204

await fetch(
  "https://app.falara.io/v1/csv-mappings/cmap_abc123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);

Errors¶

Status	Reason
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Cannot modify or delete a system template
`404 Not Found`	Template or mapping ID does not exist
`422 Unprocessable Entity`	Validation error (e.g. too many fields, missing required property)