Modtale API v1

Complete programmatic access to the Hytale community repository.

Base URL:https://api.modtale.net

Authentication & Security

Secure your requests.

All authenticated API requests must be directed to https://api.modtale.net. Include your API key in the request header to identify your client and get higher limits.

X-MODTALE-KEY: md_12345abcdef...

Rate Limits (Token Bucket)

Public Access

60 req/min

5 write/min

Perfect for browsing and testing. No key required.

Standard Key

600 req/min

60 write/min

Ideal for most apps and scripts.

Enterprise Key

5,000 req/min

500 write/min

For high-volume integrations.

Metadata & Enums

GET Public

/api/v1/tags

Retrieve the strictly enforced list of allowed project tags. Use these for search filtering or when creating/updating projects.

Response Example

[
  "Adventure", "RPG", "Sci-Fi", "Fantasy", "Survival", "Magic", "Tech",
  "Exploration", "Minigame", "PvP", "Parkour", "Hardcore", "Skyblock",
  "Puzzle", "Quests", "Economy", "Protection", "Admin Tools", "Chat",
  "Anti-Cheat", "Performance", "Library", "API", "Mechanics", "World Gen",
  "Recipes", "Loot Tables", "Functions", "Decoration", "Vanilla+",
  "Kitchen Sink", "City", "Landscape", "Spawn", "Lobby", "Medieval",
  "Modern", "Futuristic", "Models", "Textures", "Animations", "Particles"
]

GET Public

/api/v1/meta/classifications

Get allowed project types.

Response Example

[ "PLUGIN", "DATA", "ART", "SAVE", "MODPACK" ]

GET Public

/api/v1/meta/game-versions

Get supported game target versions.

Response Example

[ "2026.01.13-dcad8778f", "2026.01.17-4b0f30090" ]

GET Public

/api/v1/status

Get system health and latency statistics.

Response Example

{
  "overall": "operational",
  "services": [
    { "id": "api", "status": "operational", "latency": 12 },
    { "id": "database", "status": "operational", "latency": 24 }
  ],
  "timestamp": 1740000000000
}

Project Discovery

GET Public

/api/v1/projects

Search projects with advanced filtering. Authentication is required only for specific 'category' filters like Favorites.

Parameters (query / path / multipart)

searchstring (Keywords)

pageint (0-based, default 0)

sizeint (default 10, max 100)

classificationenum (PLUGIN|DATA|ART|SAVE|MODPACK)

tagsstring (Comma-separated list)

gameVersionstring (Exact match)

categorystring ('Favorites' | 'Your Projects' - Requires Auth)

authorstring (Filter by Author Username)

creatorstring (Alias for author)

dateRangeenum (7d, 30d, 90d, 1y, all)

Response Example

{
  "content": [
    {
      "id": "550e8400-e29b...",
      "title": "Super Tools",
      "author": "ModDev123",
      "classification": "PLUGIN",
      "description": "Adds powerful tools...",
      "imageUrl": "https://cdn.modtale.net/...",
      "downloads": 15420,
      "rating": 4.8,
      "updatedAt": "2024-03-15",
      "tags": ["Tech", "Survival"]
    }
  ],
  "totalPages": 12,
  "totalElements": 115
}

GET Public

/api/v1/projects/{id}

Get full project details including versions, gallery, and markdown description.

Response Example

{
  "id": "...",
  "title": "Super Tools",
  "description": "Short summary...",
  "about": "# Markdown Header\n\nRich text...",
  "classification": "PLUGIN",
  "status": "PUBLISHED",
  "author": "ModDev123",
  "versions": [
    {
      "id": "v1",
      "versionNumber": "1.0.0",
      "fileUrl": "files/plugin/super.jar",
      "downloadCount": 500
    }
  ],
  "galleryImages": ["https://cdn..."],
  "license": "MIT",
  "repositoryUrl": "https://github.com/..."
}

GET Auth

/api/v1/projects/user/contributed

Get a paginated list of all projects the authenticated user owns or has contributed to.

Response Example

{ "content": [ ...projects ], "totalPages": 1 }

GET Public

/api/v1/creators/{username}/projects

Get projects owned by a specific creator or organization.

Response Example

{ "content": [ ...projects ] }

Project Management

Project Lifecycle

Projects transition through these states:

POST Auth

/api/v1/projects

Initialize a new project Draft.

Validation Rules:

Title must be unique.
Description max 250 characters.
Owner field only required for Organization creation.

Parameters (query / path / multipart)

titlestring (Required)

classificationenum (Required)

descriptionstring (Required)

ownerstring (Optional Org Username for attribution)

slugstring (Optional URL slug)

Response Example

{
  "id": "new-uuid",
  "title": "My Mod",
  "status": "DRAFT",
  "expiresAt": "2024-04-19"
}

PUT Auth

/api/v1/projects/{id}

Update project metadata.

Validation Rules:

Short Description: max 250 chars.
Full Description (about): max 50,000 chars.
Repo URL: Must be valid GitHub/GitLab HTTPS URL.

Request Body (application/json)

{
  "title": "New Title",
  "description": "Updated summary",
  "about": "# Header\nUpdated markdown...",
  "tags": ["Tech", "Magic"],
  "license": "Apache-2.0",
  "repositoryUrl": "https://github.com/me/repo",
  "slug": "new-url-slug"
}

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/publish

Submit a draft for publishing. This makes the project public.

Validation Rules:

Must have at least one Version uploaded (except Modpacks).
Must have a valid License (except Modpacks).
Must have an Icon uploaded.
Must have Tags selected.

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/submit

Submit a project for admin review.

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/archive

Archive a project. It becomes read-only but remains visible.

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/unlist

Unlist a project. It is hidden from search but accessible via direct link.

Response Example

200 OK

DELETE Auth

/api/v1/projects/{id}

Delete a project.

If the project is a dependency for other active projects, it will be 'Soft Deleted' (metadata scrubbed, files kept) to prevent breaking modpacks. Otherwise, it is permanently purged.

Response Example

200 OK

Media & Assets

PUT Auth

/api/v1/projects/{id}/icon

Upload project icon.

Validation Rules:

Aspect Ratio: Exactly 1:1
Formats: PNG, JPEG, WebP
Max Size: 2MB

Parameters (query / path / multipart)

fileMultipartFile (Binary)

Response Example

200 OK

PUT Auth

/api/v1/projects/{id}/banner

Upload project banner.

Validation Rules:

Aspect Ratio: Exactly 3:1
Formats: PNG, JPEG, WebP
Max Size: 4MB

Parameters (query / path / multipart)

fileMultipartFile (Binary)

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/gallery

Add an image to the gallery.

Parameters (query / path / multipart)

fileMultipartFile (Binary)

Response Example

"https://cdn.modtale.net/gallery/image.png"

DELETE Auth

/api/v1/projects/{id}/gallery

Remove an image from the gallery.

Parameters (query / path / multipart)

imageUrlstring (Full URL)

Response Example

200 OK

Version Management

Modpack Logic: Modpacks do not have binary file uploads. They are defined by a list of dependencies (`modIds`). When a user downloads a Modpack, the API dynamically generates a ZIP file containing the manifest and all dependent files.

POST Auth

/api/v1/projects/{id}/versions

Upload a new version. Handles file uploads for mods/art/data and dependency linking for modpacks. Files are automatically scanned for malware by Warden.

Validation Rules:

Version string must be strictly SemVer X.Y.Z (e.g., 1.0.0).
File is required for standard projects (JAR/ZIP).
File is ignored for Modpacks.
Modpacks must have at least 2 dependencies.

Parameters (query / path / multipart)

versionNumberstring (Required, X.Y.Z)

gameVersionsstring[] (Required, see meta/game-versions)

changelogstring

channelenum (RELEASE | BETA | ALPHA)

fileMultipartFile (Required for non-modpacks)

modIdsstring[] (Format: 'UUID:Version' or 'UUID:Version:optional')

Response Example

200 OK

PUT Auth

/api/v1/projects/{id}/versions/{versionId}

Update version metadata (specifically dependencies for Modpacks).

Request Body (application/json)

{
  "modIds": [
    "dependency-uuid-1:1.0.0",
    "dependency-uuid-2:2.1.0:optional"
  ],
  "gameVersions": ["2026.01.17"],
  "channel": "BETA"
}

Response Example

200 OK

DELETE Auth

/api/v1/projects/{id}/versions/{versionId}

Delete a version.

Prevented if it is the ONLY version of a Published project.

Response Example

200 OK

GET Public

/api/v1/projects/{id}/versions/{version}/download-url

Generate a temporary, signed download link for a version.

Response Example

{
  "downloadUrl": "/download/token-uuid",
  "expiresIn": 300
}

GET Public

/api/v1/version/{hash}

Lookup version details by file hash (SHA-256).

Response Example

{ "id": "v1", "versionNumber": "1.0.0", "projectId": "..." }

Collaboration

POST Auth

/api/v1/projects/{id}/invite

Invite a contributor (Individual Project only, not Org).

Parameters (query / path / multipart)

usernamestring

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/invite/accept

Accept a contribution invite.

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/invite/decline

Decline a contribution invite.

Response Example

200 OK

DELETE Auth

/api/v1/projects/{id}/contributors/{username}

Remove a contributor.

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/transfer

Initiate ownership transfer to another User or Organization.

Request Body (application/json)

{ "username": "TargetUsername" }

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/transfer/resolve

Accept or decline a transfer request.

Request Body (application/json)

{ "accept": true }

Response Example

200 OK

Organizations

POST Auth

/api/v1/orgs

Create a new Organization.

Request Body (application/json)

{ "name": "MyStudio" }

Response Example

{
  "id": "org-uuid",
  "username": "MyStudio",
  "accountType": "ORGANIZATION",
  "organizationMembers": [
    { "userId": "your-id", "role": "ADMIN" }
  ]
}

GET Auth

/api/v1/user/orgs

List organizations you belong to.

Response Example

[ { "id": "...", "username": "MyStudio", "role": "ADMIN" } ]

GET Auth

/api/v1/orgs/{username}/members

Get public members of an organization.

Response Example

[ { "username": "User1", "roles": ["ADMIN"], "avatarUrl": "..." } ]

POST Auth

/api/v1/orgs/{id}/members

Invite a user to the organization (Admin only).

Request Body (application/json)

{ "username": "NewMember", "role": "MEMBER" }

Response Example

200 OK

PUT Auth

/api/v1/orgs/{id}/members/{userId}

Update member role (ADMIN/MEMBER).

Request Body (application/json)

{ "role": "ADMIN" }

Response Example

200 OK

DELETE Auth

/api/v1/orgs/{id}/members/{userId}

Remove member / Leave organization.

Response Example

200 OK

PUT Auth

/api/v1/orgs/{id}

Update organization profile.

Request Body (application/json)

{ "displayName": "My Studio", "bio": "We make mods." }

Response Example

{ ...updatedUserObj }

DELETE Auth

/api/v1/orgs/{id}

Delete organization.

Response Example

200 OK

POST Auth

/api/v1/orgs/{id}/avatar

Upload organization avatar.

Parameters (query / path / multipart)

fileMultipartFile

Response Example

"url"

POST Auth

/api/v1/orgs/{id}/banner

Upload organization banner.

Parameters (query / path / multipart)

fileMultipartFile

Response Example

"url"

User Profile & Settings

GET Public

/api/v1/users/search

Public user search.

Parameters (query / path / multipart)

querystring

Response Example

[ { "username": "Modder", "avatarUrl": "..." } ]

POST Public

/api/v1/users/batch

Batch retrieve user profiles by username.

Request Body (application/json)

{ "usernames": ["User1", "User2"] }

Response Example

[ { "username": "User1", ... }, { "username": "User2", ... } ]

GET Auth

/api/v1/user/me

Get authenticated user details.

Response Example

{
  "id": "u1",
  "username": "Me",
  "email": "[email protected]",
  "roles": ["ROLE_USER"],
  "tier": "FREE",
  "likedModIds": ["m1", "m2"],
  "followingIds": ["u2"],
  "notificationPreferences": { ... }
}

PUT Auth

/api/v1/user/profile

Update profile settings.

Request Body (application/json)

{
  "username": "NewName",
  "bio": "I make things."
}

Response Example

{ ...updatedUser }

POST Auth

/api/v1/user/profile/avatar

Upload user avatar.

Parameters (query / path / multipart)

fileMultipartFile

Response Example

"url"

POST Auth

/api/v1/user/profile/banner

Upload user banner.

Parameters (query / path / multipart)

fileMultipartFile

Response Example

"url"

GET Public

/api/v1/users/{username}/following

Get list of users this user follows.

Response Example

[ { "username": "..." } ]

GET Public

/api/v1/users/{username}/followers

Get list of users following this user.

Response Example

[ { "username": "..." } ]

PUT Auth

/api/v1/user/settings/notifications

Update notification preferences.

Request Body (application/json)

{
  "projectUpdates": "EMAIL",
  "newFollowers": "ON",
  "dependencyUpdates": "OFF",
  "creatorUploads": "ON"
}

Response Example

200 OK

POST Auth

/api/v1/user/follow/{targetUsername}

Follow a user.

Response Example

200 OK

POST Auth

/api/v1/user/unfollow/{targetUsername}

Unfollow a user.

Response Example

200 OK

DELETE Auth

/api/v1/user/me

Permanently delete user account.

Response Example

200 OK

Notifications & Analytics

GET Auth

/api/v1/notifications

Retrieve user notifications.

Response Example

[
  {
    "id": "n1",
    "title": "Project Update",
    "message": "Super Tools updated to 1.1",
    "link": "/mod/super-tools",
    "isRead": false,
    "createdAt": "2024-03-20T10:00:00",
    "type": "INFO"
  }
]

POST Auth

/api/v1/notifications/{id}/read

Mark notification as read.

Response Example

200 OK

POST Auth

/api/v1/notifications/read-all

Mark all notifications as read.

Response Example

200 OK

GET Public

/api/v1/projects/{id}/analytics

Get public stats for a project.

Parameters (query / path / multipart)

range30d | 90d | 1y

Response Example

{ "views": 500, "downloads": 120, "history": [...] }

Social Actions

POST Auth

/api/v1/projects/{id}/favorite

Toggle favorite status for a project.

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/comments

Request Body (application/json)

{
  "content": "Amazing mod!"
}

Response Example

200 OK

PUT Auth

/api/v1/projects/{id}/comments/{commentId}

Edit your comment.

Request Body (application/json)

{ "content": "Updated text" }

Response Example

200 OK

POST Auth

/api/v1/projects/{id}/comments/{commentId}/reply

Developer reply to a comment.

Request Body (application/json)

{ "reply": "Thanks!" }

Response Example

200 OK