Characters API

Overview

The Characters API allows you to:

Retrieve character lists with pagination and filtering
Get individual character details
Create new characters (Moderator+ required)
Update character information (Moderator+ required)
Delete characters (Admin only)

Endpoints

GET /api/characters

Retrieve a list of characters with optional filtering, sorting, and pagination.

Permissions: Public access

Query Parameters:

page (number, default: 1): Page number for pagination
limit (number, default: 10, max: 100): Number of items per page
q (string, optional): Search characters by name
anime (string, optional): Filter by anime series
minPower (number, optional): Minimum power level
maxPower (number, optional): Maximum power level
sortBy (string, default: "name"): Sort field (name, power, intelligence, speed, strength, createdAt)
sortOrder (string, default: "asc"): Sort order (asc, desc)

Example Request:

curl "https://api.nikode.ir/api/characters?page=1&limit=10&anime=Naruto&minPower=50"

Example Response:

{
  "success": true,
  "message": "Characters retrieved successfully",
  "data": [
    {
      "id": "char_1",
      "name": "Naruto Uzumaki",
      "anime": "Naruto",
      "power": 95,
      "intelligence": 70,
      "speed": 85,
      "strength": 80,
      "image": "https://example.com/naruto.jpg",
      "description": "The main protagonist of Naruto series",
      "abilities": ["Rasengan", "Shadow Clone Jutsu", "Sage Mode"],
      "personality": "Determined and never gives up",
      "birthday": "October 10",
      "height": "180cm",
      "weight": "75kg",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 50,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}

GETTest GET /api/characters

Retrieve characters with filtering and pagination

Query Parameters

page

limit

anime

minPower

maxPower

sortBy

sortOrder

POST /api/characters

Create a new character.

Permissions: Moderator or Admin

Request Body:

{
  "name": "string (required)",
  "anime": "string (required)",
  "power": "number (required, 0-100)",
  "intelligence": "number (required, 0-100)",
  "speed": "number (required, 0-100)",
  "strength": "number (required, 0-100)",
  "image": "string (required, URL)",
  "description": "string (required)",
  "abilities": "string[] (required)",
  "personality": "string (required)",
  "birthday": "string (optional)",
  "height": "string (optional)",
  "weight": "string (optional)"
}

Example Request:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Goku",
    "anime": "Dragon Ball",
    "power": 98,
    "intelligence": 75,
    "speed": 90,
    "strength": 95,
    "image": "https://example.com/goku.jpg",
    "description": "The main protagonist of Dragon Ball series",
    "abilities": ["Kamehameha", "Instant Transmission", "Super Saiyan"],
    "personality": "Pure-hearted and always ready for a challenge"
  }' \
  "https://api.nikode.ir/api/characters"

Example Response:

{
  "success": true,
  "message": "Character created successfully",
  "data": {
    "id": "char_new_id",
    "name": "Goku",
    "anime": "Dragon Ball",
    "power": 98,
    "intelligence": 75,
    "speed": 90,
    "strength": 95,
    "image": "https://example.com/goku.jpg",
    "description": "The main protagonist of Dragon Ball series",
    "abilities": ["Kamehameha", "Instant Transmission", "Super Saiyan"],
    "personality": "Pure-hearted and always ready for a challenge",
    "birthday": "",
    "height": "",
    "weight": "",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

POSTTest POST /api/characters

Create a new character (requires moderator or admin role)

Request Body

name *

anime *

power *

intelligence *

speed *

strength *

image *

description *

abilities *

personality *

birthday

height

weight

GET /api/characters/[id]

Retrieve a specific character by ID.

Permissions: Public access

Path Parameters:

id (string, required): Character ID

Example Request:

curl "https://api.nikode.ir/api/characters/char_1"

Example Response:

{
  "success": true,
  "message": "Character retrieved successfully",
  "data": {
    "id": "char_1",
    "name": "Naruto Uzumaki",
    "anime": "Naruto",
    "power": 95,
    "intelligence": 70,
    "speed": 85,
    "strength": 80,
    "image": "https://example.com/naruto.jpg",
    "description": "The main protagonist of Naruto series",
    "abilities": ["Rasengan", "Shadow Clone Jutsu", "Sage Mode"],
    "personality": "Determined and never gives up",
    "birthday": "October 10",
    "height": "180cm",
    "weight": "75kg",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

GETTest GET /api/characters/[id]

Retrieve a specific character by ID

Path Parameters

id *

PUT /api/characters/[id]

Update a character's information.

Permissions: Moderator or Admin

Path Parameters:

id (string, required): Character ID

Request Body (all fields optional):

{
  "name": "string",
  "anime": "string",
  "power": "number (0-100)",
  "intelligence": "number (0-100)",
  "speed": "number (0-100)",
  "strength": "number (0-100)",
  "image": "string (URL)",
  "description": "string",
  "abilities": "string[]",
  "personality": "string",
  "birthday": "string",
  "height": "string",
  "weight": "string"
}

Example Request:

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "power": 97,
    "abilities": ["Rasengan", "Shadow Clone Jutsu", "Sage Mode", "Six Paths Mode"]
  }' \
  "https://api.nikode.ir/api/characters/char_1"

Example Response:

{
  "success": true,
  "message": "Character updated successfully",
  "data": {
    "id": "char_1",
    "name": "Naruto Uzumaki",
    "anime": "Naruto",
    "power": 97,
    "intelligence": 70,
    "speed": 85,
    "strength": 80,
    "image": "https://example.com/naruto.jpg",
    "description": "The main protagonist of Naruto series",
    "abilities": [
      "Rasengan",
      "Shadow Clone Jutsu",
      "Sage Mode",
      "Six Paths Mode"
    ],
    "personality": "Determined and never gives up",
    "birthday": "October 10",
    "height": "180cm",
    "weight": "75kg",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

PUTTest PUT /api/characters/[id]

Update a character (requires moderator or admin role)

Path Parameters

id *

Request Body

name

anime

power

intelligence

speed

strength

image

description

abilities

personality

birthday

height

weight

DELETE /api/characters/[id]

Delete a character.

Permissions: Admin only

Path Parameters:

id (string, required): Character ID

Example Request:

curl -X DELETE "https://api.nikode.ir/api/characters/char_1"

Example Response:

{
  "success": true,
  "message": "Character deleted successfully",
  "data": {
    "id": "char_1",
    "name": "Naruto Uzumaki",
    "anime": "Naruto",
    "power": 95,
    "intelligence": 70,
    "speed": 85,
    "strength": 80,
    "image": "https://example.com/naruto.jpg",
    "description": "The main protagonist of Naruto series",
    "abilities": ["Rasengan", "Shadow Clone Jutsu", "Sage Mode"],
    "personality": "Determined and never gives up",
    "birthday": "October 10",
    "height": "180cm",
    "weight": "75kg",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

DELETETest DELETE /api/characters/[id]

Delete a character (requires admin role)

Path Parameters

id *

Data Models

Character Object

interface Character {
  id: string;
  name: string;
  anime: string;
  power: number; // 0-100
  intelligence: number; // 0-100
  speed: number; // 0-100
  strength: number; // 0-100
  image: string; // URL
  description: string;
  abilities: string[];
  personality: string;
  birthday: string;
  height: string;
  weight: string;
  createdAt: string; // ISO 8601
  updatedAt: string; // ISO 8601
}

Create Character Request

interface CreateCharacter {
  name: string;
  anime: string;
  power: number;
  intelligence: number;
  speed: number;
  strength: number;
  image: string;
  description: string;
  abilities: string[];
  personality: string;
  birthday?: string;
  height?: string;
  weight?: string;
}

Update Character Request

interface UpdateCharacter {
  name?: string;
  anime?: string;
  power?: number;
  intelligence?: number;
  speed?: number;
  strength?: number;
  image?: string;
  description?: string;
  abilities?: string[];
  personality?: string;
  birthday?: string;
  height?: string;
  weight?: string;
}

Error Codes

Code	Status	Description
`FORBIDDEN`	403	Insufficient permissions for operation
`NOT_FOUND`	404	Character not found
`VALIDATION_ERROR`	400	Invalid request data
`CONFLICT`	409	Character with same name already exists
`INTERNAL_ERROR`	500	Server error

Rate Limits

User: 100 requests per hour
Moderator: 500 requests per hour
Admin: 1000 requests per hour

Examples

JavaScript/Node.js

// Get all characters
const response = await fetch("/api/characters");
const characters = await response.json();

// Create a character
const newCharacter = await fetch("/api/characters", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Goku",
    anime: "Dragon Ball",
    power: 98,
    intelligence: 75,
    speed: 90,
    strength: 95,
    image: "https://example.com/goku.jpg",
    description: "The main protagonist of Dragon Ball series",
    abilities: ["Kamehameha", "Instant Transmission", "Super Saiyan"],
    personality: "Pure-hearted and always ready for a challenge",
  }),
});

Python

import requests

# Get all characters
response = requests.get('https://api.nikode.ir/api/characters')
characters = response.json()

# Create a character
new_character = requests.post(
    'https://api.nikode.ir/api/characters',
    headers={
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Goku',
        'anime': 'Dragon Ball',
        'power': 98,
        'intelligence': 75,
        'speed': 90,
        'strength': 95,
        'image': 'https://example.com/goku.jpg',
        'description': 'The main protagonist of Dragon Ball series',
        'abilities': ['Kamehameha', 'Instant Transmission', 'Super Saiyan'],
        'personality': 'Pure-hearted and always ready for a challenge'
    }
)

cURL

# Get all characters
curl "https://api.nikode.ir/api/characters"

# Get characters with filtering
curl "https://api.nikode.ir/api/characters?anime=Naruto&minPower=80&sortBy=power&sortOrder=desc"

# Create a character
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Goku",
    "anime": "Dragon Ball",
    "power": 98,
    "intelligence": 75,
    "speed": 90,
    "strength": 95,
    "image": "https://example.com/goku.jpg",
    "description": "The main protagonist of Dragon Ball series",
    "abilities": ["Kamehameha", "Instant Transmission", "Super Saiyan"],
    "personality": "Pure-hearted and always ready for a challenge"
  }' \
  "https://api.nikode.ir/api/characters"

Characters API

On this page