Skip to main content
GET
/
bindings
List bindings
curl --request GET \
  --url https://api.pictify.io/bindings \
  --header 'Authorization: Bearer <token>'
{
  "bindings": [
    {
      "uid": "<string>",
      "name": "<string>",
      "templateId": "<string>",
      "dataSource": {
        "url": "<string>"
      },
      "mapping": {},
      "defaults": {},
      "refreshPolicy": {
        "ttlSeconds": 123
      },
      "renderUrl": "<string>",
      "webhookUrl": "<string>",
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "totalPages": 123,
    "hasNext": true,
    "hasPrev": true
  }
}

​
Bindings

Bindings connect templates to external data sources, enabling automatic image generation when data changes. Perfect for dynamic dashboards, real-time stats, and automated social media images.
For a step-by-step tutorial, see Webhook Integration.

​
How Bindings Work

[Your Data API] → [Binding] → [Template] → [Updated Image]
  1. Create a binding — link a template to an external data URL
  2. Pictify fetches data — based on your refresh policy
  3. Template renders — variables from the data are injected into the template
  4. Image updates — the rendered image URL stays the same, content updates automatically

​
Endpoints

MethodEndpointDescription
GET/bindingsList bindings
POST/bindingsCreate binding
GET/bindings/{uid}Get binding
PUT/bindings/{uid}Update binding
DELETE/bindings/{uid}Delete binding

​
Binding Status

StatusDescription
activeBinding is active and refreshing
pausedTemporarily disabled
errorFailed to fetch data or render

​
Refresh Policy Types

TypeDescription
ttlRefresh after time-to-live expires (default, 60-604800 seconds)
etagRefresh when ETag changes
webhookRefresh when webhook is triggered
manualOnly refresh when manually triggered

​
Data Mapping

Map fields from your API response to template variables using dot notation and array access: 
{
  "mapping": {
    "title": "name",
    "stars": "stargazers_count",
    "userName": "user.name",
    "firstItem": "items[0].name"
  }
}

​
Data Source Authentication

TypeDescription
api_keyAPI key authentication
bearer_tokenBearer token in Authorization header
basic_authUsername/password authentication
custom_headerCustom header name and value

​
Binding Events

Subscribe to binding events via Webhooks:
EventDescription
binding.updatedBinding successfully refreshed
binding.failedBinding refresh failed

​
Best Practices

  1. Set appropriate TTL — don’t refresh more often than data changes
  2. Use defaults — provide fallback values for missing fields
  3. Handle errors gracefully — use serve_stale for critical images
  4. Monitor binding health — set up webhooks for binding.failed events
  5. Test before deploying — validate your data source and mapping first

Authorizations

​
Authorization
string
header
required

API key obtained from the Pictify dashboard

Query Parameters

​
templateId
string
​
status
enum<string>
Available options:
active,
paused,
error
​
page
integer
default:1
​
limit
integer
default:20

Response

200 - application/json

List of bindings

​
bindings
object[]
​
pagination
object