Open API Documentation

Request body: {} or omitted.

Response 200

{
  "firmware": "B100V050610",
  "nickname": "Inkanva",
  "lastHeartbeat": "2026-06-16T06:56:25.782Z",
  "isCharging": false,
  "batteryLevel": 100,
  "sdUsedSize": 0,
  "switchType": "queue",
  "switchMinute": 60,
  "imageId": 423,
  "coverId": null,
  "timezone": "America/Adak",
  "point": 30,
  "screenWidth": 800,
  "screenHeight": 480,
  "screenRotate": 270,
  "synced": false,
  "online": false
}

Field Notes

firmware

Current firmware version.

nickname

Device nickname.

lastHeartbeat

ISO8601 timestamp of the last heartbeat.

isCharging, batteryLevel

Current power state.

switchType, switchMinute

Image change strategy and interval.

screenWidth, screenHeight, screenRotate

Display geometry.

synced, online

Latest-image sync and connection status.

cURL

curl -X POST https://api.inkanva.com/openapi/device \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

Request Body

{
  "base64": "/9j/4AAQSkZJRgABAQEAAAAAAAD...",
  "name": "photo.jpg"
}

Rules and Behavior

• base64 is required and must contain raw base64 image data without a data URL prefix.
• The frame image counter is incremented and the new image becomes active.
• name is optional and defaults to the original filename.
• Images are automatically cropped to the display area; match the screen ratio when possible.

Response 200

{ "id": 789, "counter": 10 }

cURL

curl -X POST https://api.inkanva.com/openapi/upload \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"base64":"<BASE64_DATA>","name":"photo.jpg"}'

Request body: {} or omitted.

Response 200

{
  "total": 2,
  "list": [
    {
      "id": 789,
      "name": "photo.jpg",
      "fileId": "abc123.jpg",
      "size": 182736,
      "type": "image/jpeg",
      "width": 800,
      "height": 480,
      "createdAt": "2026-05-14T08:00:00.000Z",
      "updatedAt": "2026-05-14T08:00:00.000Z",
      "current": true
    }
  ]
}

Field Notes

• total is the number of images belonging to the device.
• list contains images ordered by ID descending.
• current is true when the image is currently active.

cURL

curl -X POST https://api.inkanva.com/openapi/listImages \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

Request Body

{ "imageId": 123 }

Rules and Behavior

• imageId is required and must belong to the device.
• The image file and database record are deleted together.
• The frame image counter is incremented after deletion.
• If the active image is deleted, the server switches to the next available image.
• If no images remain, the current image becomes null.

Response 200

{
  "success": true,
  "id": 123,
  "imageId": 122,
  "counter": 11
}

Errors

• 500 with { "message": "imageId is empty" } when the ID is missing or invalid.
• 500 with { "message": "image not found" } when the image does not belong to the device.

cURL

curl -X POST https://api.inkanva.com/openapi/deleteImage \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"imageId":123}'

Path Parameters

apikey

Device API key shown on the Frame settings page.

imageId

Image ID returned by the upload or list APIs.

The API key is passed in the URL path, so the Authorization header is not required.

Behavior

• Returns the original stored image file.
• The image must belong to the device identified by apikey.
• The response type is derived from the stored file extension, typically image/jpeg.

Response 200

Binary image stream.

Errors

• 404 with { "message": "image not found" } for an invalid or unrelated image ID.
• 500 with { "message": "can not find robot <apikey>" } for an unknown device key.

cURL

curl -L "https://api.inkanva.com/openapi/image/<API_KEY>/123" \
  -o image.jpg

Request Body

{ "imageId": 123 }

Response 200

{ "success": true }

Returns 500 with { "message": "image not found" } when the image does not belong to the device.

cURL

curl -X POST https://api.inkanva.com/openapi/displayImageById \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"imageId":123}'

Request Body

{ "imageName": "photo.jpg" }

Response 200

{ "success": true }

Returns 500 with { "message": "image not found" } when the image name is not found.

cURL

curl -X POST https://api.inkanva.com/openapi/displayImageByName \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"imageName":"photo.jpg"}'

Both return HTTP 200 JSON. /state also includes an images array of filenames. Use /info to check readiness and confirm display results, even if the SD card is unavailable.

apiVersion, enabled, activationId

API version, local-mode state, and activation identifier. Resetting and reactivating changes the identifier.

serial, firmware, battery, charging

Device identifier, firmware version, battery percentage, and charging state.

networkMode, ip, ssid, hostname

ap for hotspot or sta for home Wi-Fi, plus the current address and network name.

wifiConnected, wifiRssi

Home Wi-Fi connection status and signal strength; false / 0 in hotspot mode.

sdReady, storageTotalMB, storageUsedMB

Storage readiness, total capacity, and used capacity.

current, displayed

Selected filename versus the last successfully displayed, saved photo. Selection changes before the screen finishes.

refreshing, displayStatus, lastDisplayFile

Whether display work is pending; idle / pending / succeeded / failed; and the latest requested filename in this boot.

showingConnectionGuide

Whether the connection guide is being shown. The saved displayed value still refers to the previous photo.

panelWidth, panelHeight

Physical panel dimensions in pixels.

uploadWidth, uploadHeight, uploadFormat

Suggested dimensions for the current orientation, and jpg or y4.

maxUploadBytes, frameColorMode

Upload limit (16 MiB) and the model’s photo color mode.

apiEnabled, sleepSeconds, awakeSeconds

Local API access and timing settings.

slideshow, order, interval, orientation

Current playback settings; interval is in seconds.

Example /images response · 200

{
  "images": ["local_1.jpg", "local_2.jpg"],
  "current": "local_2.jpg",
  "displayed": "local_1.jpg",
  "refreshing": true
}

Download a thumbnail

curl -H "Authorization: Bearer $TOKEN" \
  "$FRAME/api/v1/image?name=local_1.jpg&thumbnail=1" \
  -o thumbnail.jpg

Use filenames returned by the frame. Omit thumbnail=1 for the saved JPEG; if no thumbnail exists, that JPEG is returned anyway. On 28.5-inch frames the .jpg entry is the preview, with display data stored in the associated .y4 file. Image downloads can be busy during refresh; the album list uses cached names.

For uploadFormat="jpg". Send a decodable baseline JPEG, up to 16 MiB, with an optional JPEG thumbnail no larger than 640 × 640 pixels. Crop to the suggested upload dimensions; the firmware can scale valid JPEGs.

curl -H "Authorization: Bearer $TOKEN" \
  -F 'image=@photo.jpg;filename=photo.jpg;type=image/jpeg' \
  -F 'thumbnail=@thumbnail.jpg;filename=thumbnail.jpg;type=image/jpeg' \
  "$FRAME/api/v1/upload?show=0&uploadId=album-photo-001"

• Send the main image first, then the optional thumbnail. Use thumbnail.jpg for the thumbnail filename; keep thumbnail out of the main image filename.
• show=0 saves only, useful for batch uploads. Omitting it, or using show=1, saves and requests display.
• HTTP 201 returns the assigned filename: {"file":"local_3.jpg"}. Keep it for subsequent show or delete requests.
• Optional query parameters jpgBytes and thumbnailBytes declare file sizes for additional integrity checks.
• uploadId accepts up to 64 letters, numbers, hyphens, or underscores. Only the most recent successful upload is remembered, including across restarts. If its response is lost, retry the same file with the same ID before starting another upload. This is not a permanent duplicate-photo check.

These models need panel-ready Y4 display data plus a JPEG preview; the JPEG upload endpoint cannot replace that data. For manual uploads, use the frame’s browser interface to prepare the image. Custom integrations must produce the Y4 format below.

curl -H "Authorization: Bearer $TOKEN" \
  -F 'display=@photo.y4;filename=photo.y4;type=application/octet-stream' \
  -F 'thumbnail=@thumbnail.jpg;filename=thumbnail.jpg;type=image/jpeg' \
  "$FRAME/api/v1/upload-y4?show=0&uploadId=poster-001"

cat photo.y4 thumbnail.jpg > upload.bin
Y4_BYTES=$(wc -c < photo.y4 | tr -d '[:space:]')
THUMB_BYTES=$(wc -c < thumbnail.jpg | tr -d '[:space:]')

curl -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/octet-stream' \
  -H "X-Upload-Y4-Bytes: $Y4_BYTES" \
  -H "X-Upload-Thumbnail-Bytes: $THUMB_BYTES" \
  -H 'X-Upload-Show: 0' \
  -H 'X-Upload-Id: poster-002' \
  --data-binary @upload.bin \
  "$FRAME/api/v1/upload-y4-bin"

# Display a saved image
curl -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'name=local_3.jpg' "$FRAME/api/v1/show"

# Move through the album (no request body)
curl -H "Authorization: Bearer $TOKEN" -X POST "$FRAME/api/v1/next"
curl -H "Authorization: Bearer $TOKEN" -X POST "$FRAME/api/v1/previous"

Show, next, and previous return HTTP 200 with {"current":"local_3.jpg"} when accepted. Next and previous follow the configured sequential or random playback strategy and wrap around the album. An empty album returns 404. Wait for each refresh to finish before sending another change.

Delete an image you no longer need

curl -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'name=local_1.jpg' "$FRAME/api/v1/delete"

Deletion removes the photo, thumbnail, and any associated Y4 data. HTTP 200 returns ok, current, and refreshing. Deleting the selected photo selects the next one; deleting the last photo shows the local upload guide. Confirm the filename before deleting.

For example, rotate through an album once per hour in portrait orientation:

curl -H "Authorization: Bearer $TOKEN" \
  -d 'slideshow=1&order=sequence&interval=3600&orientation=portrait' \
  "$FRAME/api/v1/settings"

All four parameters are required on every request:

slideshow

0 off, 1 on.

order

sequence or random.

interval

300 / 3600 / 21600 / 43200 / 86400 / 604800 seconds: 5 minutes, 1 hour, 6 hours, 12 hours, 1 day, or 1 week.

orientation

portrait or landscape.

HTTP 200 includes orientationChanged, refreshing, and updated upload dimensions. Changing orientation schedules a redraw; prepare future uploads to the new dimensions. These settings do not change the Local API sleep interval.

GET reads the current configuration. POST updates it; include apiEnabled=0 or 1 every time. Omitted optional values stay unchanged. For example, allow a longer testing window:

curl -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'apiEnabled=1' \
  --data-urlencode 'sleepSeconds=300' \
  --data-urlencode 'awakeSeconds=60' \
  "$FRAME/api/v1/config"

Both return HTTP 200 with apiEnabled, wifiSsid, sleepSeconds, awakeSeconds, token, and hostname. The Wi-Fi password is never returned. Keep the response private because it contains your access token.

• Optional wifiSsid: up to 32 bytes; must be nonempty when enabling the API. Optional wifiPassword: up to 64 bytes; omit to retain it, or explicitly send an empty value for an open network.
• sleepSeconds: 60–3600. awakeSeconds: 10–3600. Invalid parameters return 400 without changing the configuration.
• Saving from home Wi-Fi ends the current service window after the response and any pending display work. The next wake uses the new settings. Saving in the hotspot keeps it open so you can copy your token.
• Disabling Local API stops scheduled LAN service. Restart and reconnect to the hotspot to enable it again.

curl -H "Authorization: Bearer $TOKEN" -X POST "$FRAME/api/v1/heartbeat"

# After the display has finished refreshing:
curl -H "Authorization: Bearer $TOKEN" -X POST "$FRAME/api/v1/sleep"

Heartbeat returns 204 with no body. Sleep returns 202, for example {"ok":true,"sleepSeconds":300,"timerWake":true}, and closes the service shortly afterward. If a refresh is pending, sleep returns 423; wait and retry. When both API and slideshow are disabled, timerWake=false; restart the frame to reconnect.