Update Template

Update an existing image template.

You will need to authenticate to use this API. See authentication.

The template system supports various Handlebars helpers for dynamic content manipulation. Check out the Template Helpers section to learn about available helpers for formatting dates, performing calculations, manipulating strings, and more.

Request


PUT https://api.ojo.so/v1/template/:templateId

PATCH on the same path does the same. Fields you leave out keep their value.

Path Parameters

Parameter	Type	Description
templateId	string	The unique identifier of the template to update

Headers

Header	Value	Description
Content-Type	application/json	Specify that the request body is JSON

Request Body

Field	Type	Description
html	string	(Optional) The HTML of the template, as a plain string
variables	object	(Optional) Variables used in the template
name	string	(Optional) The template’s name, 1 to 120 characters
description	string	(Optional) A description of the template, at most 300 characters
viewportWidth	number	(Optional) The template’s default width in pixels
viewportHeight	number	(Optional) The template’s default height in pixels

Send at least one field. A name or description alone changes it without rendering a new preview.

Send the HTML as a plain JSON string. Your JSON library escapes quotes, newlines and other characters for you:


// JavaScript example
const body = JSON.stringify({ html: '<h1>{{title}}</h1>', variables: { title: 'Hello' } });


# Python example
import json
body = json.dumps({'html': '<h1>{{title}}</h1>', 'variables': {'title': 'Hello'}})

Dynamic Template

You can update your template with Handlebars expressions and generate images by providing the necessary data. When making a request to generate an image, include a modify object in your request body with the data to populate your Handlebars placeholders. Learn how to create image with variables.

Example:


{
  "templateId": "template-uuid-123",
  "modify": {
    "title": "Welcome to Our Site",
    "user": {
      "name": "Alice Smith"
    },
    "showDetails": true,
    "items": ["Item 1", "Item 2", "Item 3"]
  }
}

cURL


curl --request PUT \
  --url https://api.ojo.so/v1/template/<Replace with template ID> \
  --header 'Authorization: Bearer <your API key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "html": "<h1>{{title}}</h1>",
    "variables": {
      "title": "Updated Template Title",
      "content": "This is the updated content."
    }
  }'

Python


import requests
import json
 
url = "https://api.ojo.so/v1/template/<Replace with template ID>"
 
payload = json.dumps({
"html": "<h1>{{title}}</h1>",
"variables": {
"title": "Updated Template Title",
"content": "This is the updated content."
}
})
headers = {
'Authorization': 'Bearer <your API key>',
'Content-Type': 'application/json'
}
 
response = requests.request("PUT", url, headers=headers, data=payload)
 
print(response.text)

JavaScript


const options = {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer <your API key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    html: '<h1>{{title}}</h1>',
    variables: {
      title: 'Updated Template Title',
      content: 'This is the updated content.'
    }
  })
};
 
fetch('https://api.ojo.so/v1/template/<Replace with template ID>', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

PHP


<?php
 
$curl = curl_init();
 
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ojo.so/v1/template/<Replace with template ID>",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'html' => '<h1>{{title}}</h1>',
'variables' => [
'title' => 'Updated Template Title',
'content' => 'This is the updated content.'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <your API key>",
"Content-Type: application/json"
],
]);
 
$response = curl_exec($curl);
$err = curl_error($curl);
 
curl_close($curl);
 
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

Go


package main
 
import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)
 
func main() {
  url := "https://api.ojo.so/v1/template/<Replace with template ID>"
 
  payload := strings.NewReader(`{
    "html": "<h1>{{title}}</h1>",
    "variables": {
      "title": "Updated Template Title",
      "content": "This is the updated content."
    }
  }`)
 
  req, _ := http.NewRequest("PUT", url, payload)
 
  req.Header.Add("Authorization", "Bearer <your API key>")
  req.Header.Add("Content-Type", "application/json")
 
  res, _ := http.DefaultClient.Do(req)
 
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)
 
  fmt.Println(string(body))
}

Java


OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"html\": \"<h1>{{title}}</h1>\",\n  \"variables\": {\n    \"title\": \"Updated Template Title\",\n    \"content\": \"This is the updated content.\"\n  }\n}");
Request request = new Request.Builder()
  .url("https://api.ojo.so/v1/template/<Replace with template ID>")
  .method("PUT", body)
  .addHeader("Authorization", "Bearer <your API key>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Response

200

Template successfully updated.


{
  "id": "template-uuid-1",
  "message": "Template updated"
}

401

Your API key might be invalid or expired.


{
  "error": true,
  "message": "Unauthorized",
  "status": 401,
  "title": "Unauthorized",
  "detail": "Unauthorized"
}

404

The specified template was not found.


{
  "error": true,
  "message": "Template not found",
  "status": 404,
  "title": "Not Found",
  "detail": "Template not found"
}

422

Request payload unprocessable. The reason is in logs. Update necessary fields and try again.


{
  "error": true,
  "message": "Unprocessable Entity",
  "logs": ["`html` must be a string"],
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "Unprocessable Entity"
}

429

You have hit your rate limit. You can view rate limit details here.


{
  "error": true,
  "message": "Template rate limit reached: 30 template requests per minute",
  "logs": ["Try again in 2 minutes."],
  "code": "rate_limited.template",
  "retryAfter": 120,
  "status": 429,
  "title": "Too Many Requests",
  "detail": "Template rate limit reached: 30 template requests per minute"
}

500

An unexpected error occurred. Try again later. If the issue persists, please reach out.


{
  "error": true,
  "message": "Internal Server Error",
  "status": 500,
  "title": "Internal Server Error",
  "detail": "Internal Server Error"
}