Modtale API v1

Complete programmatic access to the Hytale community repository.

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

Authentication

Secure your requests.

All API requests must be directed to https://api.modtale.net. For server-to-server communication or scripts, include your API key in the request header. Headers are also returned in every response to help you track your quota usage.

X-MODTALE-KEY: md_12345abcdef...

Rate Limits

Standard

300 req/min

Default for personal API keys.

Enterprise

2,000 req/min

High volume application integration.

No Auth

10 req/min

Aggressively throttled. Auth recommended.

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

[ "Release 1.1", "Release 1.0", "Beta 0.9" ]

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 (Username)

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 }

Project Management

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)

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"
}

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.
Must have an Icon uploaded.
Must have Tags selected.

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). 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

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

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

POST Auth

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

Upload a new version. Handles file uploads for mods/art/data and dependency linking for modpacks.

Validation Rules:

Version string must be strictly 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)

changelogstring

channelenum (RELEASE | BETA | ALPHA)

fileMultipartFile

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"
  ]
}

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

Download version file.

For Modpacks, this dynamically generates a .zip containing a manifest.json and all required dependency files.

Response Example

Binary Stream (application/octet-stream)

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.

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 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"

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

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/{id}/unread

Mark notification as unread.

Response Example

200 OK

POST Auth

/api/v1/notifications/read-all

Mark all notifications as read.

Response Example

200 OK

DELETE Auth

/api/v1/notifications/{id}

Delete a notification.

Response Example

200 OK

DELETE Auth

/api/v1/notifications/clear-all

Delete all notifications.

Response Example

200 OK

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}/reviews

Post a review.

Request Body (application/json)

{
  "rating": 5,
  "comment": "Amazing mod!",
  "version": "1.0.0"
}

Response Example

200 OK