v1.0.0

API Reference

Build game backend features in minutes. Our APIs are designed for indie developers who want surgical-grade infrastructure without the complexity.

1 Authentication

All API requests require a valid API key from your DYMOL Dashboard. Pass it in the Authorization header.

Header

Authorization: Bearer dymol_sk_...

2 Base URL

All endpoints are relative to this base URL. Replace YOUR_PROJECT with your project slug.

Base URL

https://api.dymol.dev/v1

3 Error Handling

401 Unauthorized

Missing or invalid API key

403 Forbidden

Key not bound to a project

400 Bad Request

Missing required fields

404 Not Found

Resource doesn't exist

Error Response Format

{
  "error": "Unauthorized: Invalid API Key"
}

ReactionAPI

Sentiment-as-a-Service

Quick Start

using UnityEngine.Networking

using UnityEngine;
using UnityEngine.Networking;
using System.Text;
using System.Collections;

public class DymolReactions : MonoBehaviour {
    private string apiKey = "YOUR_API_KEY";

    public IEnumerator AddReaction(string targetId, string type, string userId) {
        string url = "https://api.dymol.dev/v1/react";
        string json = $"{{\"target_id\":\"{targetId}\",\"type\":\"{type}\",\"user_id\":\"{userId}\"}}";
        
        using (UnityWebRequest www = new UnityWebRequest(url, "POST")) {
            byte[] bodyRaw = Encoding.UTF8.GetBytes(json);
            www.uploadHandler = new UploadHandlerRaw(bodyRaw);
            www.downloadHandler = new DownloadHandlerBuffer();
            www.SetRequestHeader("Content-Type", "application/json");
            www.SetRequestHeader("Authorization", $"Bearer {apiKey}");
            yield return www.SendWebRequest();
        }
    }
}

extends Node

extends Node

var api_key = "YOUR_API_KEY"

func add_reaction(target_id: String, type: String, user_id: String):
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(_http_request_completed)

    var url = "https://api.dymol.dev/v1/react"
    var headers = [
        "Content-Type: application/json",
        "Authorization: Bearer " + api_key
    ]
    var body = JSON.stringify({
        "target_id": target_id,
        "type": type,
        "user_id": user_id
    })

    var error = http_request.request(url, headers, HTTPClient.METHOD_POST, body)
    if error != OK:
        push_error("HTTP Request Error")

func _http_request_completed(result, response_code, headers, body):
    if response_code == 200:
        print("Reaction sent!")

async function addReaction()

const apiKey = "YOUR_API_KEY";

async function addReaction(targetId, type, userId) {
  const response = await fetch("https://api.dymol.dev/v1/react", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      target_id: targetId,
      type: type,
      user_id: userId
    })
  });
  return response.json();
}

import requests

import requests

api_key = "YOUR_API_KEY"

def add_reaction(target_id, type, user_id):
    url = "https://api.dymol.dev/v1/react"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }
    payload = {
        "target_id": target_id,
        "type": type,
        "user_id": user_id
    }
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

POST `/v1/react`

Submit or update a reaction. Uses upsert — if the same user reacts again to the same target, their previous reaction is overwritten.

Request Body

{
  "target_id": "level_99",
  "type": "fire",
  "user_id": "player_123"
}

target_id string

The ID of the target (level, post, item)

type string

Reaction type e.g. fire, like, heart

user_id string

Unique player identifier

GET `/v1/reactions`

Get a global aggregation of all reactions, broken down by target_id.

Response

{
  "success": true,
  "data": {
    "total_reactions": 3,
    "global_distribution": {
      "fire": 2,
      "heart": 1
    },
    "targets": {
      "level_99": { "fire": 1 },
      "junk_20": { "fire": 1, "heart": 1 }
    }
  }
}

PromoCode API

Create limited promo codes for in-game rewards

Quick Start

using UnityEngine.Networking

using UnityEngine;
using UnityEngine.Networking;
using System.Text;
using System.Collections;

public class DymolPromoCodes : MonoBehaviour {
    private string apiKey = "YOUR_API_KEY";

    public IEnumerator RedeemPromoCode(string codeId, string userId) {
        string url = "https://api.dymol.dev/v1/promo/redeem";
        string json = $"{{\"code_id\":\"{codeId}\",\"user_id\":\"{userId}\"}}";
        
        using (UnityWebRequest www = new UnityWebRequest(url, "POST")) {
            byte[] bodyRaw = Encoding.UTF8.GetBytes(json);
            www.uploadHandler = new UploadHandlerRaw(bodyRaw);
            www.downloadHandler = new DownloadHandlerBuffer();
            www.SetRequestHeader("Content-Type", "application/json");
            www.SetRequestHeader("Authorization", $"Bearer {apiKey}");
            yield return www.SendWebRequest();
            
            if (www.result == UnityWebRequest.Result.Success) {
                string response = www.downloadHandler.text;
                Debug.Log("Promo response: " + response);
            } else {
                Debug.LogError("Promo error: " + www.error);
            }
        }
    }
}

extends Node

extends Node

var api_key = "YOUR_API_KEY"

func redeem_promo_code(code_id: String, user_id: String):
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(_on_redeem_completed)

    var url = "https://api.dymol.dev/v1/promo/redeem"
    var headers = [
        "Content-Type: application/json",
        "Authorization: Bearer " + api_key
    ]
    var body = JSON.stringify({
        "code_id": code_id,
        "user_id": user_id
    })

    var error = http_request.request(url, headers, HTTPClient.METHOD_POST, body)
    if error != OK:
        push_error("HTTP Request Error")

func _on_redeem_completed(result, response_code, headers, body):
    if response_code == 200:
        var json = JSON.parse_string(body.get_string_from_utf8())
        if json.status == "SUCCESS":
            print("Code redeemed!")
        elif json.status == "ALREADY_CLAIMED":
            print("You already used this code")
        elif json.status == "EXHAUSTED":
            print("Code is no longer valid")
        else:
            print("Invalid code")
    else:
        print("Request failed")

async function redeemPromoCode()

const apiKey = "YOUR_API_KEY";

async function redeemPromoCode(codeId, userId) {
  const response = await fetch("https://api.dymol.dev/v1/promo/redeem", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      code_id: codeId,
      user_id: userId
    })
  });
  const data = await response.json();
  
  if (data.status === "SUCCESS") {
    console.log("Reward granted!", data.data);
  } else if (data.status === "ALREADY_CLAIMED") {
    console.warn("You already redeemed this code");
  } else {
    console.error("Redeem failed:", data.error);
  }
  return data;
}

import requests

import requests

api_key = "YOUR_API_KEY"

def redeem_promo_code(code_id, user_id):
    url = "https://api.dymol.dev/v1/promo/redeem"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }
    payload = {
        "code_id": code_id,
        "user_id": user_id
    }
    response = requests.post(url, json=payload, headers=headers)
    data = response.json()
    
    if data["status"] == "SUCCESS":
        print(f"Redeemed! {data['data']['claims_count']}/{data['data']['max_claims']} used")
    elif data["status"] == "ALREADY_CLAIMED":
        print("You already used this code")
    else:
        print(f"Failed: {data.get('error', 'Unknown error')}")
    return data

POST `/v1/promo/redeem`

Redeem a promo code for a specific user. Each user can only redeem a code once. The code is automatically deactivated when claims_count reaches max_claims. The request is scoped to the project associated with the API key.

Request Body

{
  "code_id": "SUMMER2025",
  "user_id": "player_123"
}

code_id string

The promo code to redeem (case-insensitive)

user_id string

Unique player identifier (prevents duplicate redemptions)

SUCCESS Response

{
  "status": "SUCCESS",
  "message": "Promo code redeemed successfully",
  "data": {
    "code_id": "SUMMER2025",
    "claims_count": 42,
    "max_claims": 1000
  }
}

ALREADY_CLAIMED Response

{
  "status": "ALREADY_CLAIMED",
  "error": "You have already redeemed this code"
}

Status Codes

SUCCESS — Code redeemed, reward granted

ALREADY_CLAIMED — This user already redeemed this code

EXHAUSTED — Code reached max claims or was deactivated

INVALID — Code does not exist in this project

CounterAPI

Track any in-game event with automatic aggregation

Quick Start

using UnityEngine.Networking

using UnityEngine;
using UnityEngine.Networking;
using System.Text;
using System.Collections;

public class DymolCounters : MonoBehaviour {
    private string apiKey = "YOUR_API_KEY";

    public IEnumerator IncrementCounter(string targetId, string userId, int amount = 1) {
        string url = "https://api.dymol.dev/v1/counter/increment";
        string json = $"{{\"target_id\":\"{targetId}\",\"user_id\":\"{userId}\",\"amount\":{amount}}}";
        
        using (UnityWebRequest www = new UnityWebRequest(url, "POST")) {
            byte[] bodyRaw = Encoding.UTF8.GetBytes(json);
            www.uploadHandler = new UploadHandlerRaw(bodyRaw);
            www.downloadHandler = new DownloadHandlerBuffer();
            www.SetRequestHeader("Content-Type", "application/json");
            www.SetRequestHeader("Authorization", $"Bearer {apiKey}");
            yield return www.SendWebRequest();
            
            if (www.result == UnityWebRequest.Result.Success) {
                Debug.Log("Counter incremented!");
            }
        }
    }
}

extends Node

extends Node

var api_key = "YOUR_API_KEY"

func increment_counter(target_id: String, user_id: String, amount: int = 1):
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(_on_increment_completed)

    var url = "https://api.dymol.dev/v1/counter/increment"
    var headers = [
        "Content-Type: application/json",
        "Authorization: Bearer " + api_key
    ]
    var body = JSON.stringify({
        "target_id": target_id,
        "user_id": user_id,
        "amount": amount
    })

    var error = http_request.request(url, headers, HTTPClient.METHOD_POST, body)
    if error != OK:
        push_error("HTTP Request Error")

func _on_increment_completed(result, response_code, headers, body):
    if response_code == 200:
        var json = JSON.parse_string(body.get_string_from_utf8())
        print("Count: " + str(json.data.count))

async function incrementCounter()

const apiKey = "YOUR_API_KEY";

async function incrementCounter(targetId, userId, amount = 1) {
  const response = await fetch("https://api.dymol.dev/v1/counter/increment", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      target_id: targetId,
      user_id: userId,
      amount: amount
    })
  });
  const data = await response.json();
  console.log("Count:", data.data.count);
  return data;
}

import requests

import requests

api_key = "YOUR_API_KEY"

def increment_counter(target_id, user_id, amount=1):
    url = "https://api.dymol.dev/v1/counter/increment"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }
    payload = {
        "target_id": target_id,
        "user_id": user_id,
        "amount": amount
    }
    response = requests.post(url, json=payload, headers=headers)
    data = response.json()
    print(f"Count: {data['data']['count']}")
    return data

POST `/v1/counter/increment`

Increment a counter for a specific target. Uses upsert — if the target doesn't exist, it's created automatically. Each increment is logged for analytics.

Request Body

{
  "target_id": "boss_dragon_defeated",
  "user_id": "player_123",
  "amount": 1
}

target_id string, required

The ID of the event to count (e.g. "blocks_broken", "level_started")

user_id string, optional

Unique player identifier (logged for analytics)

amount integer, optional

Amount to increment by (default 1, max 1,000,000)

Response

{
  "success": true,
  "message": "Counter incremented successfully",
  "data": {
    "target_id": "boss_dragon_defeated",
    "count": 1542
  }
}

GET `/v1/counter`

Get aggregated counters for all targets in your project, plus the global total.

Response

{
  "success": true,
  "data": {
    "total_counts": 15420,
    "targets": {
      "blocks_broken": 8400,
      "boss_dragon_defeated": 1542,
      "level_started": 5478
    }
  }
}

GET `/v1/counter/:target_id`

Get the current count for a specific target.

Response

{
  "success": true,
  "data": {
    "target_id": "boss_dragon_defeated",
    "count": 1542
  }
}

GET `/v1/counter/daily`

Get daily aggregated counter data for the last 7 days (or specify days query param). Optionally filter by target_id.

Response

{
  "success": true,
  "data": [
    { "day": "2026-05-04", "count": 120 },
    { "day": "2026-05-05", "count": 245 },
    { "day": "2026-05-06", "count": 189 },
    { "day": "2026-05-07", "count": 312 },
    { "day": "2026-05-08", "count": 278 },
    { "day": "2026-05-09", "count": 401 },
    { "day": "2026-05-10", "count": 156 }
  ]
}

DeathAPI

Track player death coordinates for heatmap analysis

Quick Start

using UnityEngine.Networking

using UnityEngine;
using UnityEngine.Networking;
using System.Text;
using System.Collections;

public class DymolDeaths : MonoBehaviour {
    private string apiKey = "YOUR_API_KEY";

    public IEnumerator RecordDeath(string levelId, Vector3 pos, string cause) {
        string url = "https://api.dymol.dev/v1/deaths";
        string json = $"{{\"level_id\":\"{levelId}\",\"x\":{pos.x},\"y\":{pos.y},\"z\":{pos.z},\"cause\":\"{cause}\"}}";

        using (UnityWebRequest www = new UnityWebRequest(url, "POST")) {
            byte[] bodyRaw = Encoding.UTF8.GetBytes(json);
            www.uploadHandler = new UploadHandlerRaw(bodyRaw);
            www.downloadHandler = new DownloadHandlerBuffer();
            www.SetRequestHeader("Content-Type", "application/json");
            www.SetRequestHeader("Authorization", $"Bearer {apiKey}");
            yield return www.SendWebRequest();
        }
    }
}

extends Node

extends Node

var api_key = "YOUR_API_KEY"

func record_death(level_id: String, pos: Vector3, cause: String = ""):
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(_on_death_completed)

    var url = "https://api.dymol.dev/v1/deaths"
    var headers = [
        "Content-Type: application/json",
        "Authorization: Bearer " + api_key
    ]
    var body = JSON.stringify({
        "level_id": level_id,
        "x": pos.x,
        "y": pos.y,
        "z": pos.z,
        "cause": cause
    })

    var error = http_request.request(url, headers, HTTPClient.METHOD_POST, body)
    if error != OK:
        push_error("HTTP Request Error")

func _on_death_completed(result, response_code, headers, body):
    if response_code == 200:
        print("Death recorded")

async function recordDeath()

const apiKey = "YOUR_API_KEY";

async function recordDeath(levelId, x, y, z, cause = "") {
  const response = await fetch("https://api.dymol.dev/v1/deaths", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({ level_id: levelId, x, y, z, cause })
  });
  return response.json();
}

import requests

import requests

api_key = "YOUR_API_KEY"

def record_death(level_id, x, y, z, cause=""):
    url = "https://api.dymol.dev/v1/deaths"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }
    payload = {
        "level_id": level_id,
        "x": x,
        "y": y,
        "z": z,
        "cause": cause
    }
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

POST `/v1/deaths`

Record a player death with 3D coordinates. Use this from your game client every time a player dies.

Request Body

{
  "level_id": "level_1",
  "x": 12.5,
  "y": 3.2,
  "z": -7.8,
  "cause": "fall"
}

level_id string, required

The level or map where the death occurred

x, y, z number, required

3D coordinates of the death location

cause string, optional

Death cause (e.g. "fall", "enemy", "lava")

Response

{
  "success": true,
  "message": "Death recorded successfully",
  "data": { "id": 42 }
}

GET `/v1/deaths/:level_id`

Retrieve death coordinates for a specific level. Returns up to 1000 records ordered by created_at DESC. Use this in the Unity Editor to generate a 3D heatmap.

Response

{
  "success": true,
  "data": [
    {
      "x": 12.50,
      "y": 3.20,
      "z": -7.80,
      "cause": "fall",
      "created_at": "2026-05-17T10:32:00Z"
    }
  ]
}

Home Dashboard

API Reference

1 Authentication

2 Base URL

3 Error Handling

ReactionAPI

Quick Start

POST /v1/react

GET /v1/reactions

PromoCode API

Quick Start

POST /v1/promo/redeem

CounterAPI

Quick Start

POST /v1/counter/increment

GET /v1/counter

GET /v1/counter/:target_id

GET /v1/counter/daily

DeathAPI

Quick Start

POST /v1/deaths

GET /v1/deaths/:level_id

POST `/v1/react`

GET `/v1/reactions`

POST `/v1/promo/redeem`

POST `/v1/counter/increment`

GET `/v1/counter`

GET `/v1/counter/:target_id`

GET `/v1/counter/daily`

POST `/v1/deaths`

GET `/v1/deaths/:level_id`