Miniviz Quick Start Guide (For AI)

📋 About This Document

This document is a complete guide on how to use Miniviz (a BI platform for IoT systems). When asking questions to an AI, paste this entire document for reference.

How to Use:

Copy this entire document and paste it to an AI
Ask specific questions like "I want to implement XX with Miniviz" or "How do I send △△ using Miniviz API?"
The AI will reference this document to provide answers

Information Included in This Document:

Basic usage of Miniviz (7 steps)
Complete data transmission API specification (endpoints, request format, constraints)
Complete image transmission API specification (Pro plan only)
Sample code (curl, Python)
Data type constraints and limitations

Key Points:

Data transmission API: POST https://api.miniviz.net/api/project/{project_id}?token={token}
Image transmission API: POST https://api.miniviz.net/api/project/{project_id}/image?token={token} (Pro plan only)
Payload constraints: Maximum 8 keys, 400 bytes, flat structure only (no nesting)
Image constraints: 200KB max, 60 seconds/image, JPEG/PNG only

Overall Flow

Create/Login to Miniviz Account
Create Project
(Device Side) Send Data
Check Data (Database)
Create Charts
Configure Notifications
(Pro Plan Only) Send Images

1. Create/Login to Miniviz Account

2. Create Project

Create a project to manage your data.

Copy Project ID and Token

Copy the project ID and token as they will be needed in the next step.

Click the token icon on the right side of the project screen
The project ID and token will be displayed - copy them
The token copied here will be used on the device side

3. (Device Side) Send Data

Send data from the device side. We recommend first testing data transmission with curl commands or a simple Python script.

API Endpoint

POST https://api.miniviz.net/api/project/{project_id}?token={token}

Request Overview

Data transmission to Miniviz API uses the POST method. The request body is in JSON format.

Request Body

Field Name	Type	Required	Description
`timestamp`	number	Yes	Transmission time (UNIX time in milliseconds)
`label_key`	string	Yes	Label to identify the sender (device name, location, etc.)
`payload`	object	Yes	Actual measurement values. Specify any metric name as key, and numeric or string value

Data Type Constraints

Acceptable Data Types

String Type (str)

No constraints (no character limit)
Examples: "device-001", "Temperature Sensor", "Hello World"

Numeric Types

Integer (int): No constraints (no range limit)
Floating Point (float): No constraints (no range limit)
Examples: 42, -10, 3.14, -99.9

Unacceptable Types

The following types cannot be used as payload values:

Dictionary (dict): Nested objects are not allowed
Array (list, tuple, set): Array types are not allowed
Boolean (bool): Not allowed (use string "true"/"false" or numeric 1/0)
null/None: Not allowed

Payload Overall Constraints

Number of keys: Maximum 8
Size: Maximum 400 bytes after JSON encoding
Structure: Flat (no nesting)

Request Example

{
  "timestamp": 1731129600000,
  "label_key": "raspberry_pi_home",
  "payload": {
    "temperature": 25,
    "humidity": 55,
    "switch": "true",
    "system_status": "running"
  }
}

curl Command (Linux/MacOS)

timestamp_ms=$(( $(date -u +%s) * 1000 ))

curl -X POST \
  "https://api.miniviz.net/api/project/{project_id}?token={token}" \
  -H "Content-Type: application/json" \
  -d "{
        \"timestamp\": ${timestamp_ms},
        \"label_key\": \"Local_PC\",
        \"payload\": {
          \"temperature\": 25,
          \"humidity\": 55,
          \"switch\": \"true\",
          \"system_status\": \"running\"
        }
      }"

Python Sample Code

When using Python, you can send data with code like this:

import time
from datetime import datetime, timezone
import requests

PROJECT_ID = "MINIVIZ_PROJECT_ID"
TOKEN = "MINIVIZ_API_TOKEN"
API_URL = "https://api.miniviz.net"
LABEL_KEY = "Local_PC"
SEND_INTERVAL = 90  # seconds

def send_data():
    url = f"{API_URL}/api/project/{PROJECT_ID}?token={TOKEN}"
    timestamp_ms = int(datetime.now(timezone.utc).timestamp() * 1000)

    response = requests.post(url, json={
        "timestamp": timestamp_ms,
        "label_key": LABEL_KEY,
        "payload": {
            "temperature": 25,
            "humidity": 55,
            "switch": "true",
            "system_status": "running"
        }
    })

    if response.ok:
        data = response.json()
        print(f"Send successful (id={data.get('id')})")
    else:
        print(f"Send failed: {response.status_code} {response.text}")

if __name__ == "__main__":
    print("Starting miniviz data send test (press Ctrl+C to stop)")
    while True:
        send_data()
        time.sleep(SEND_INTERVAL)

4. Check Data (Database)

Check data from the Database menu. Sent data is saved in the database.

Note: If data is not displayed here, data transmission has failed. Please check the device-side logs again.

5. Create Charts

Create charts from the Visualize menu. You can configure chart types and data display formats.

Select chart type (line chart, bar chart, etc.)
Select sent data as data source
Verify that the chart displays correctly

6. Configure Notifications

Configure notification destinations such as Slack and Webhooks. Configure notifications from the Rules menu.

Slack Notification Configuration

Configure notifications from the Rules menu
Enter Slack Webhook URL
Set thresholds and conditions
Notifications will be sent when the set thresholds are exceeded

7. Send Images (Pro Plan Only)

Pro plan allows you to send images using the image transmission API.

API Endpoint

POST https://api.miniviz.net/api/project/{project_id}/image?token={token}

Request Overview

Image transmission to Miniviz API uses the POST method. The request body is in JSON format. Image data must be base64 encoded before sending.

Request Body (Image Transmission)

Field Name	Type	Required	Description
`timestamp`	number	Yes	Transmission time (UNIX time in milliseconds)
`label_key`	string	Yes	Label to identify the sender (128 characters max, [A-Za-z0-9-_.:@/] only)
`image_name`	string	Yes	Image file name (255 characters max)
`image_base64`	string	Yes	Base64 encoded image data (200KB max)

Limitations

Image Size and Format

Image size: Maximum 200KB per image (size after base64 encoding)
Supported formats: JPEG and PNG only
Transmission interval: 60 seconds/image (managed per label key)
Retention period: 30 days

※Export functionality is scheduled to be released around December 2025.

Plan Restrictions

Available plans: Pro plan only (free plan returns 403 error)

Request Example (Image Transmission)

{
  "timestamp": 1717587812345,
  "label_key": "camera_1",
  "image_name": "image.jpg",
  "image_base64": "base64_encoded_image_data"
}

curl Command (Linux/MacOS) - Image Transmission

timestamp_ms=$(( $(date -u +%s) * 1000 ))

# Encode image file to base64
image_base64=$(base64 -i image.jpg)

curl -X POST \
  "https://api.miniviz.net/api/project/{project_id}/image?token={token}" \
  -H "Content-Type: application/json" \
  -d "{
        \"timestamp\": ${timestamp_ms},
        \"label_key\": \"camera_1\",
        \"image_name\": \"image.jpg\",
        \"image_base64\": \"${image_base64}\"
      }"

Python Sample Code - Image Transmission

import requests
import base64
import os
from datetime import datetime, timezone

PROJECT_ID = "PROJECT_ID"
TOKEN = "TOKEN"
API_URL = "https://api.miniviz.net"
IMAGE_PATH = "image.jpg"
LABEL_KEY = "camera_1"

# Encode image to base64
with open(IMAGE_PATH, "rb") as f:
    image_data = f.read()
image_base64 = base64.b64encode(image_data).decode('utf-8')

# Send request
url = f"{API_URL}/api/project/{PROJECT_ID}/image"
payload = {
    "timestamp": int(datetime.now(timezone.utc).timestamp() * 1000),
    "label_key": LABEL_KEY,
    "image_name": os.path.basename(IMAGE_PATH),
    "image_base64": image_base64
}

try:
    response = requests.post(url, json=payload, params={"token": TOKEN})
    response.raise_for_status()
    print("✅ Send successful")
    print(response.json())
except requests.exceptions.HTTPError as e:
    print(f"❌ Error: HTTP {e.response.status_code}")
    print(e.response.text)
except Exception as e:
    print(f"❌ Error: {e}")

Viewing Images

You can preview sent images from the database page
You can also display images in charts from the chart creation page
- [Create New Chart] -> [Select Chart Type] -> Select [image]

Summary

Miniviz provides the following features:

Data Transmission: Send sensor data from IoT devices
Data Visualization: Check data in the database
Chart Creation: Visualize sent data in charts
Notification Configuration: Send notifications via Slack or Webhook when thresholds are exceeded
Image Transmission: Send and visualize image data (Pro plan)

API Endpoints:

Data transmission: POST https://api.miniviz.net/api/project/{project_id}?token={token}
Image transmission: POST https://api.miniviz.net/api/project/{project_id}/image?token={token}

Constraints:

Payload: Maximum 8 keys, 400 bytes, flat structure only
Images: 200KB max, 60 seconds/image, Pro plan only

📋 About This Document​

Overall Flow​

1. Create/Login to Miniviz Account​

2. Create Project​

Copy Project ID and Token​

3. (Device Side) Send Data​

API Endpoint​

Request Overview​

Request Body​

Data Type Constraints​

Acceptable Data Types​

Unacceptable Types​

Payload Overall Constraints​

Request Example​

curl Command (Linux/MacOS)​

Python Sample Code​

4. Check Data (Database)​

5. Create Charts​

6. Configure Notifications​

Slack Notification Configuration​

7. Send Images (Pro Plan Only)​

API Endpoint​

Request Overview​

Request Body (Image Transmission)​

Limitations​

Image Size and Format​

Plan Restrictions​

Request Example (Image Transmission)​

curl Command (Linux/MacOS) - Image Transmission​

Python Sample Code - Image Transmission​

Viewing Images​

Summary​

📋 About This Document

Overall Flow

1. Create/Login to Miniviz Account

2. Create Project

Copy Project ID and Token

3. (Device Side) Send Data

API Endpoint

Request Overview

Request Body

Data Type Constraints

Acceptable Data Types

Unacceptable Types

Payload Overall Constraints

Request Example

curl Command (Linux/MacOS)

Python Sample Code

4. Check Data (Database)

5. Create Charts

6. Configure Notifications

Slack Notification Configuration

7. Send Images (Pro Plan Only)

API Endpoint

Request Overview

Request Body (Image Transmission)

Limitations

Image Size and Format

Plan Restrictions

Request Example (Image Transmission)

curl Command (Linux/MacOS) - Image Transmission

Python Sample Code - Image Transmission

Viewing Images

Summary