Create Image Variable (Folder)

This endpoint creates a reusable variable scoped to a template folder or to your organization's global knowledge base, independent of any single template. Despite the name, it is not limited to images: mimeType also accepts text and html, and the same endpoint is used for Read Variables (Folder) to later list.

When to use it

Use this endpoint to build a shared library of content, such as a company logo, a standard address block, or boilerplate legal language, that multiple templates can reference by placeholder without duplicating the content in each one.

Example request

curl -X POST "https://api.turbodocx.com/Variable" \
  -H "Authorization: Bearer $TURBODOCX_API_KEY" \
  -H "x-rapiddocx-org-id: $TURBODOCX_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Logo",
    "placeholder": "{CompanyLogo}",
    "mimeType": "image",
    "text": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "templateFolderId": "9d2b1c63-0f77-4a9c-b1d0-2c5e6f7a8b90",
    "allowRichTextInjection": true
  }'

Optionally send templateFolderId (scopes the variable to that folder) or isGlobal: true (adds it to your org-wide knowledge base); at most one may be set, and sending both is rejected. text must be a base64 data: URI when mimeType is "image", or plain text/HTML otherwise. placeholder must be unique within its folder or knowledge base and, if set, must be wrapped in curly braces, for example {CompanyLogo}.

Example response

On success the endpoint returns the created variable:

{
  "data": {
    "results": {
      "variable": {
        "id": "e4f5a6b7-8c9d-4e0f-a1b2-3c4d5e6f7a8b",
        "name": "Company Logo",
        "placeholder": "{CompanyLogo}",
        "mimeType": "image",
        "isGlobal": false,
        "templateFolderId": "9d2b1c63-0f77-4a9c-b1d0-2c5e6f7a8b90",
        "allowRichTextInjection": true,
        "orgId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "createdBy": "f5e6d7c8-9a0b-4c1d-2e3f-4a5b6c7d8e9f",
        "createdOn": "2026-05-01T14:22:10.000Z"
      }
    }
  }
}

Common errors

Status	When	Response body
401	Missing or invalid API key/token, or the organization cannot be resolved	Empty (status only)
403	The key's role is not administrator, contributor, or user	Empty (status only)
403	isGlobal: true and the key's role is user (creating a knowledge-base variable requires administrator or contributor)	Empty (status only)
400	mimeType or text is missing, or both isGlobal and templateFolderId are set	{ "message", "type": "ValidationError", "data": { "errors": [...] } }
400	placeholder is not wrapped in { }, or already exists in that folder or knowledge base	{ "message", "type": "TemplateError", "data": [{ "message", "type", "data": { "explanation", "context" } }] }

Related endpoints

• Read Variables (Folder) to list variables you have created

• Update Variable by ID to edit a variable after creating it

• Delete Variables (by IDs) to remove variables in bulk

  POST

  /Variable