Skip to main content

Getting Started

The OKZest API uses REST. Send request bodies as JSON with Content-Type: application/json. Creating an image returns the image itself (a JPEG by default), not JSON.

An API key is required to authenticate the request.

  1. Create an account at OKZest
  2. Create an API key
  3. Create a design
  4. Check your key with GET /v1/whoami
  5. Make an API call to change some of the content

Check your key first​

Before you create an image, make one call that only checks your key:

curl https://api.okzest.com/v1/whoami   -H "x-api-key: API KEY GOES HERE"

A valid key returns 200 with the account the key belongs to and the name you gave the key:

{
  "company_id": "...",
  "key_name": "My first key"
}

If you get 200, your key works, so any later error is about the request you sent. A missing or wrong key returns 401. See Who am I for the full reference.

Create your first image​

var data = {
    "design_id": "dcH69PLkb2YctQunAVZLQ",
    "layers": [
        {
            "layer_id": "static-text",
            "color": "#FF5733"
        },        
        {
            "layer_id": "dynamic-text",
            "text": "Hello from the API"
        }
    ],
    "background": {
        "color": "#eda32b"
    }
}

fetch('https://api.okzest.com/v1/images', {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'x-api-key' : 'API KEY GOES HERE' 
  }
})

Authentication​

You can view and manage your API keys from the API page.

Send your key in the x-api-key header on every request.

An API key acts as the user who created it, with that user's project permissions, just like the dashboard. It only lists, reads and renders designs in projects where that user is a member with permission to view designs, and any other design is reported as not found. Permissions are checked on every request, so changing a user's permissions in a project changes what their existing keys can see straight away.

Your API keys give access to your design data so be sure to keep them secure. Do not share your secret API keys in public areas such as GitHub or client-side code.

All API requests must be made over HTTPS.

Errors​

A successful request returns 200. These are the errors you can get:

  • 401 - the x-api-key header is missing, empty or not a valid key.
  • 400 - the request was understood but can't be used. The body is a plain-text message, for example Design not found. or Request body is null.
  • 404 - the path doesn't exist. Check you are calling https://api.okzest.com/v1/images.
  • 5xx - the problem is on our side. Retry the request, and contact support if it keeps failing.

For causes and fixes, including 401, 400 and 429 responses and blank images, see Troubleshooting and FAQ.