API Reference

Complete reference for the DITO Agent API. All endpoints support JSON requests and responses with comprehensive error handling.

Introduction

The DITO API is built for AI agents and modern applications. It provides a single command endpoint that accepts natural language instructions, making it perfect for integration with OpenClaw, Claude, ChatGPT, and other AI systems.

Base URL

https://api.dito.guru

Authentication

All API requests must include a valid Bearer token in the Authorization header:

Authorization: Bearer your-api-token

High-security operations require 2FA verification using TOTP codes.

Error Handling

The API uses conventional HTTP response codes and returns detailed error information:

200 - Success

Request completed successfully

400 - Bad Request

Invalid request parameters

401 - Unauthorized

Invalid or missing authentication

403 - Forbidden

2FA verification required

404 - Not Found

Resource does not exist

500 - Server Error

Internal server error

Error Response Format

{
  "success": false,
  "message": "Human readable error message",
  "error": {
    "code": "error_code",
    "type": "error_type",
    "details": {}
  },
  "meta": {
    "timestamp": "2026-03-16T10:30:00Z",
    "request_id": "req_12345",
    "version": "1.0.0"
  }
}

2FA Status

POST /command

Check the current 2FA status for the authenticated user.

Request Body

{
  "action": "2fa_status"
}

Response

{
  "success": true,
  "data": {
    "enabled": true,
    "backup_codes_remaining": 6,
    "last_used": "2026-03-16T10:15:00Z"
  }
}

Setup 2FA

POST /command

Initialize 2FA setup and receive QR code for authenticator app.

Request Body

{
  "action": "2fa_setup"
}

Response

{
  "success": true,
  "data": {
    "qr_code_url": "https://api.qrserver.com/v1/create-qr-code/...",
    "manual_entry_key": "JBSWY3DPEHPK3PXP",
    "backup_codes": [
      "12345678",
      "87654321"
    ]
  }
}

Get Soul

POST /command

Retrieve information about the current user's soul.

Request Body

{
  "action": "get_soul"
}

Response

{
  "success": true,
  "data": {
    "id": "roy-soul",
    "seeker_name": "Roy",
    "current_level": "Flame",
    "ember_points": 1250,
    "total_talents": 7,
    "active_talents": 3,
    "conviction_level": 68,
    "arena_eligible": true,
    "last_activity": "2026-03-16T10:30:00Z",
    "talents": [
      {
        "id": "programming-talent",
        "name": "프로그래밍",
        "category": "analytical",
        "progress_percentage": 85,
        "ember_earned": 420,
        "days_active": 45,
        "mastery_level": "advanced"
      }
    ]
  }
}

List Talents

POST /command

Get a list of all available talents and their progress status.

Request Body

{
  "action": "list_talents",
  "category": "creative",
  "status": "in_progress"
}

Parameters

Parameter	Type	Description
`category` optional	string	Filter by talent category (creative, analytical, social, physical)
`status` optional	string	Filter by progress status (discovered, in_progress, completed)

Start Talent Journey

POST /command

Begin developing a new talent with evidence and goals.

Request Body

{
  "action": "start_talent_journey",
  "talent_label": "Web Development",
  "description": "Learning modern web development",
  "evidence": "GitHub portfolio: https://github.com/user/repo",
  "goals": ["Build 3 full-stack projects", "Master React and Node.js"]
}

Parameters

Parameter	Type	Description
`talent_label` required	string	Name of the talent to develop
`description` optional	string	Detailed description of the talent journey
`evidence` optional	string	Initial evidence or portfolio links
`goals` optional	array	List of specific goals for this journey

List Arena Events

POST /command

Get all active arena events available for participation.

Request Body

{
  "action": "get_arena_events",
  "status": "active",
  "category": "coding"
}

Response

{
  "success": true,
  "data": [
    {
      "id": "coding-championship-2026",
      "title": "Coding Championship 2026",
      "description": "Annual programming competition",
      "category": "coding",
      "status": "active",
      "start_time": "2026-03-20T09:00:00Z",
      "end_time": "2026-03-20T18:00:00Z",
      "participants": 127,
      "max_participants": 200,
      "entry_fee": 50,
      "reward_pool": 10000
    }
  ]
}

Get Ember Balance

POST /command

Check the current EMBER token balance for the authenticated user.

Request Body

{
  "action": "get_ember_balance"
}

Response

{
  "success": true,
  "data": {
    "balance": 1250,
    "pending": 50,
    "total_earned": 5420,
    "total_spent": 4220,
    "last_transaction": "2026-03-16T10:15:00Z"
  }
}

Transfer Ember

POST /command

Transfer EMBER tokens to another soul. Large transfers may require 2FA verification.

Request Body

{
  "action": "transfer_ember",
  "recipient_id": "soul-12345",
  "amount": "100",
  "note": "Payment for mentoring session",
  "totp_code": "123456"
}

Parameters

Parameter	Type	Description
`recipient_id` required	string	Soul ID of the recipient
`amount` required	string	Amount of EMBER to transfer
`note` optional	string	Optional note for the transaction
`totp_code` conditional	string	Required for transfers > 500 EMBER