Modtale API

https://modtale.net/api-docs
Admin
Modtale API provides complete programmatic access to the Hytale community repository, enabling...
Tokens:12,222
Snippets:61
Trust Score:4.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Get Project Details (API)

Source: https://modtale.net/api-docs/index

Retrieves full details for a specific project, including its versions, gallery, and markdown description. This endpoint provides comprehensive information about a project.

```json
{
  "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 User Contributed Projects (API)

Source: https://modtale.net/api-docs/index

Fetches a paginated list of all projects that the authenticated user either owns or has contributed to. This is useful for managing your contributions.

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

--------------------------------

### Get Organization Members API

Source: https://modtale.net/api-docs/index

Retrieves a list of public members for a given organization. Requires authentication.

```HTTP
GET /api/v1/orgs/{username}/members
```

--------------------------------

### Get Authenticated User Details

Source: https://modtale.net/api-docs/index

Retrieves the details of the currently authenticated user, including their ID, username, email, roles, tier, liked mods, and followed users.

```json
{
  "id": "u1",
  "username": "Me",
  "email": "me@example.com",
  "roles": ["ROLE_USER"],
  "tier": "FREE",
  "likedModIds": ["m1", "m2"],
  "followingIds": ["u2"],
  "notificationPreferences": { ... }
}
```

--------------------------------

### Initialize New Project Draft (API)

Source: https://modtale.net/api-docs/index

Initializes a new project draft. This endpoint requires authentication and has validation rules for title uniqueness, description length, and owner field for organizations.

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

--------------------------------

### Project Management

Source: https://modtale.net/api-docs/index

Create, update, and manage projects.

```APIDOC
## POST /api/v1/projects

### Description
Initialize a new project Draft.

### Method
POST

### Endpoint
/api/v1/projects

### Authentication
Required (API Key in header: X-MODTALE-KEY)

### Parameters
#### Request Body (multipart/form-data)
- **title** (string) - Required - The title of the project.
- **classification** (enum) - Required - The type of project (`PLUGIN`, `DATA`, `ART`, `SAVE`, `MODPACK`).
- **description** (string) - Required - A short description of the project (max 250 characters).
- **owner** (string) - Optional - The username of the organization owner if creating an organization project.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the newly created project.
- **title** (string) - The title of the project.
- **status** (string) - The initial status of the project (e.g., `DRAFT`).
- **expiresAt** (string) - The expiration date of the draft project.

#### Response Example
```json
{
  "id": "new-uuid",
  "title": "My Mod",
  "status": "DRAFT",
  "expiresAt": "2024-04-19"
}
```
```

```APIDOC
## PUT /api/v1/projects/{id}

### Description
Update project metadata.

### Method
PUT

### Endpoint
/api/v1/projects/{id}

### Authentication
Required (API Key in header: X-MODTALE-KEY)

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project to update.

#### Request Body (application/json)
- **title** (string) - Optional - The new title of the project.
- **description** (string) - Optional - Updated short description (max 250 chars).
- **about** (string) - Optional - Updated full description in Markdown (max 50,000 chars).
- **tags** (array[string]) - Optional - List of tags to associate with the project.
- **license** (string) - Optional - The project's license.
- **repositoryUrl** (string) - Optional - URL to the project's repository (Must be valid GitHub/GitLab HTTPS URL).

### Response
#### Success Response (200)
Indicates the project metadata was updated successfully.

#### Response Example
```
200 OK
```
```

```APIDOC
## POST /api/v1/projects/{id}/publish

### Description
Submit a draft project for publishing. This action makes the project public.

### Method
POST

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

### Authentication
Required (API Key in header: X-MODTALE-KEY)

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project to publish.

### Validation Rules
- Must have at least one Version uploaded (except for Modpacks).
- Must have a valid License specified.
- Must have an Icon uploaded.
- Must have Tags selected.

### Response
#### Success Response (200)
Indicates the project was successfully submitted for publishing.

#### Response Example
```
200 OK
```
```

```APIDOC
## POST /api/v1/projects/{id}/archive

### Description
Archive a project. The project becomes read-only but remains visible.

### Method
POST

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

### Authentication
Required (API Key in header: X-MODTALE-KEY)

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project to archive.

### Response
#### Success Response (200)
Indicates the project was successfully archived.

#### Response Example
```
200 OK
```
```

--------------------------------

### Project Discovery

Source: https://modtale.net/api-docs/index

Search and retrieve project information.

```APIDOC
## GET /api/v1/projects

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

### Method
GET

### Endpoint
/api/v1/projects

### Parameters
#### Query Parameters
- **searchstring** (string) - Keywords to search for.
- **page** (integer) - 0-based page number, default 0.
- **size** (integer) - Number of results per page, default 10, max 100.
- **sort** (enum) - Sorting order: `relevance`, `downloads`, `updated`, `newest`, `rating`, `favorites`.
- **classification** (enum) - Filter by project type: `PLUGIN`, `DATA`, `ART`, `SAVE`, `MODPACK`.
- **tags** (string) - Comma-separated list of tags.
- **gameVersion** (string) - Exact match for game version.
- **category** (string) - Filter by category: `Favorites` or `Your Projects` (Requires Auth).
- **author** (string) - Filter by author's username.

### Response
#### Success Response (200)
- **content** (array[object]) - Array of project summaries.
  - **id** (string) - Unique project identifier.
  - **title** (string) - Project title.
  - **author** (string) - Project author's username.
  - **classification** (string) - Project type.
  - **description** (string) - Short project description.
  - **imageUrl** (string) - URL to the project's image.
  - **downloads** (integer) - Total number of downloads.
  - **rating** (float) - Average rating.
  - **updatedAt** (string) - Date of last update.
  - **tags** (array[string]) - List of tags associated with the project.
- **totalPages** (integer) - Total number of pages available.
- **totalElements** (integer) - Total number of projects matching the query.

#### Response Example
```json
{
  "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
}
```
```

```APIDOC
## GET /api/v1/projects/{id}

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

### Method
GET

### Endpoint
/api/v1/projects/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **id** (string) - Unique project identifier.
- **title** (string) - Project title.
- **description** (string) - Short project summary.
- **about** (string) - Detailed project description in Markdown format.
- **classification** (string) - Project type.
- **status** (string) - Current status of the project (e.g., DRAFT, PUBLISHED).
- **author** (string) - Project author's username.
- **versions** (array[object]) - List of project versions.
  - **id** (string) - Version identifier.
  - **versionNumber** (string) - Version number.
  - **fileUrl** (string) - URL to the version's file.
  - **downloadCount** (integer) - Number of downloads for this version.
- **galleryImages** (array[string]) - URLs to gallery images.
- **license** (string) - Project's license.
- **repositoryUrl** (string) - URL to the project's repository.

#### Response Example
```json
{
  "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/..."
}
```
```

```APIDOC
## GET /api/v1/projects/user/contributed

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

### Method
GET

### Endpoint
/api/v1/projects/user/contributed

### Authentication
Required (API Key in header: X-MODTALE-KEY)

### Response
#### Success Response (200)
- **content** (array[object]) - Array of project summaries.
- **totalPages** (integer) - Total number of pages available.

#### Response Example
```json
{ "content": [ ...projects ], "totalPages": 1 }
```
```

--------------------------------

### Media & Assets

Source: https://modtale.net/api-docs/index

Endpoints for uploading project icons, banners, and managing gallery images.

```APIDOC
## PUT /api/v1/projects/{id}/icon

### Description
Upload project icon. Aspect Ratio must be 1:1, and formats accepted are PNG, JPEG, WebP.

### Method
PUT

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
#### Form Data Parameters
- **fileMultipartFile** (Binary) - Required - The project icon file.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## PUT /api/v1/projects/{id}/banner

### Description
Upload project banner. Aspect Ratio must be 3:1, and formats accepted are PNG, JPEG, WebP.

### Method
PUT

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
#### Form Data Parameters
- **fileMultipartFile** (Binary) - Required - The project banner file.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## POST /api/v1/projects/{id}/gallery

### Description
Add an image to the project gallery.

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
#### Form Data Parameters
- **fileMultipartFile** (Binary) - Required - The image file to add to the gallery.

### Response
#### Success Response (200)
- **imageUrl** (string) - The URL of the uploaded image.

#### Response Example
```json
"https://cdn.modtale.net/gallery/image.png"
```
```

```APIDOC
## DELETE /api/v1/projects/{id}/gallery

### Description
Remove an image from the project gallery.

### Method
DELETE

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
#### Query Parameters
- **imageUrl** (string) - Required - The full URL of the image to remove.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

--------------------------------

### Metadata & Enums

Source: https://modtale.net/api-docs/index

Retrieve lists of allowed project tags, classifications, and supported game versions.

```APIDOC
## GET /api/v1/tags

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

### Method
GET

### Endpoint
/api/v1/tags

### Response
#### Success Response (200)
- **tags** (array[string]) - List of available project tags.

#### Response Example
```json
[
  "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"
]
```
```

```APIDOC
## GET /api/v1/meta/classifications

### Description
Get allowed project types.

### Method
GET

### Endpoint
/api/v1/meta/classifications

### Response
#### Success Response (200)
- **classifications** (array[string]) - List of allowed project classifications.

#### Response Example
```json
[ "PLUGIN", "DATA", "ART", "SAVE", "MODPACK" ]
```
```

```APIDOC
## GET /api/v1/meta/game-versions

### Description
Get supported game target versions.

### Method
GET

### Endpoint
/api/v1/meta/game-versions

### Response
#### Success Response (200)
- **versions** (array[string]) - List of supported game versions.

#### Response Example
```json
[ "2026.01.13-dcad8778f", "2026.01.17-4b0f30090" ]
```
```

--------------------------------

### Submit Project for Publishing (API)

Source: https://modtale.net/api-docs/index

Submits a project draft for publishing, making it public. This action has several validation rules, including having at least one version uploaded (except for Modpacks), a valid license, an uploaded icon, and selected tags.

```http
POST /api/v1/projects/{id}/publish

200 OK
```

--------------------------------

### Initiate Ownership Transfer API

Source: https://modtale.net/api-docs/index

Initiates the transfer of project ownership to another user or organization. Requires authentication and a JSON request body specifying the target username.

```HTTP
POST /api/v1/projects/{id}/transfer
Content-Type: application/json

{
  "username": "TargetUsername"
}
```

--------------------------------

### Search Projects (API)

Source: https://modtale.net/api-docs/index

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

```json
{
  "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
}
```

--------------------------------

### Accept Contribution Invite API

Source: https://modtale.net/api-docs/index

Accepts an invitation to contribute to a project. Requires authentication.

```HTTP
POST /api/v1/projects/{id}/invite/accept
```

--------------------------------

### Version Management

Source: https://modtale.net/api-docs/index

Endpoints for uploading, updating, deleting, and downloading project versions.

```APIDOC
## POST /api/v1/projects/{id}/versions

### Description
Upload a new version. Handles file uploads for mods/art/data and dependency linking for modpacks. Version string must be strictly X.Y.Z. File is required for standard projects (JAR/ZIP) and ignored for Modpacks. Modpacks must have at least 2 dependencies.

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
#### Form Data Parameters
- **versionNumber** (string) - Required - The version string in X.Y.Z format.
- **gameVersions** (string[]) - Required - An array of game versions this version is compatible with.
- **changelog** (string) - Optional - A description of the changes in this version.
- **channel** (enum) - Optional - The release channel (RELEASE, BETA, ALPHA).
- **fileMultipartFile** (Binary) - Optional - The project file (e.g., JAR/ZIP) for standard projects.
- **modIds** (string[]) - Optional - An array of dependency identifiers in 'UUID:Version' or 'UUID:Version:optional' format. Required for Modpacks.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## PUT /api/v1/projects/{id}/versions/{versionId}

### Description
Update version metadata, specifically dependencies for Modpacks.

### Method
PUT

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
- **versionId** (string) - Required - The unique identifier of the version.
#### Request Body
- **modIds** (string[]) - Required - An array of dependency identifiers in 'UUID:Version' or 'UUID:Version:optional' format.

### Request Example
```json
{
  "modIds": [
    "dependency-uuid-1:1.0.0",
    "dependency-uuid-2:2.1.0:optional"
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## DELETE /api/v1/projects/{id}/versions/{versionId}

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

### Method
DELETE

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
- **versionId** (string) - Required - The unique identifier of the version.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## GET /api/v1/projects/{id}/versions/{version}/download

### Description
Download version file. For Modpacks, this dynamically generates a .zip containing a manifest.json and all required dependency files.

### Method
GET

### Endpoint
/api/v1/projects/{id}/versions/{version}/download

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
- **version** (string) - Required - The version string of the project to download.

### Response
#### Success Response (200)
- **file** (Binary Stream) - The project file or a generated zip archive for modpacks.

#### Response Example
```
Binary Stream (application/octet-stream)
```
```

--------------------------------

### Retrieve Supported Game Versions (API)

Source: https://modtale.net/api-docs/index

Fetches the list of game versions that are currently supported by the API. This information is useful for ensuring compatibility when developing or submitting projects.

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

--------------------------------

### Upload Project Icon API

Source: https://modtale.net/api-docs/index

Uploads a project icon with specific validation rules for aspect ratio (1:1) and formats (PNG, JPEG, WebP). Requires authentication and a multipart file upload.

```HTTP
PUT /api/v1/projects/{id}/icon
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="icon.png"
Content-Type: image/png

<binary data>
```

--------------------------------

### Download Project Version API

Source: https://modtale.net/api-docs/index

Allows downloading the file for a specific project version. For modpacks, it dynamically generates a zip archive containing a manifest and all dependencies. Publicly accessible.

```HTTP
GET /api/v1/projects/{id}/versions/{version}/download
```

--------------------------------

### Project Management

Source: https://modtale.net/api-docs/index

Endpoints for unlisting, deleting, and managing project details.

```APIDOC
## POST /api/v1/projects/{id}/unlist

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

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## DELETE /api/v1/projects/{id}

### Description
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.

### Method
DELETE

### Endpoint
/api/v1/projects/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

--------------------------------

### Collaboration

Source: https://modtale.net/api-docs/index

Endpoints for managing project contributors and ownership.

```APIDOC
## POST /api/v1/projects/{id}/invite

### Description
Invite a contributor to an Individual Project (not an Organization).

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
#### Query Parameters
- **username** (string) - Required - The username of the user to invite.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## POST /api/v1/projects/{id}/invite/accept

### Description
Accept a contribution invite.

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## POST /api/v1/projects/{id}/invite/decline

### Description
Decline a contribution invite.

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## DELETE /api/v1/projects/{id}/contributors/{username}

### Description
Remove a contributor from a project.

### Method
DELETE

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
- **username** (string) - Required - The username of the contributor to remove.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## POST /api/v1/projects/{id}/transfer

### Description
Initiate ownership transfer of a project to another User or Organization.

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
#### Request Body
- **username** (string) - Required - The username or organization name to transfer ownership to.

### Request Example
```json
{
  "username": "TargetUsername"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## POST /api/v1/projects/{id}/transfer/resolve

### Description
Accept or decline a project ownership transfer request.

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
#### Request Body
- **accept** (boolean) - Required - True to accept the transfer, false to decline.

### Request Example
```json
{
  "accept": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

--------------------------------

### Post Project Review

Source: https://modtale.net/api-docs/index

Submits a review for a specific project. This endpoint requires a JSON request body containing the rating, comment, and version of the mod being reviewed.

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

--------------------------------

### Upload Project Version API

Source: https://modtale.net/api-docs/index

Uploads a new version for a project, handling file uploads for mods/art/data and dependency linking for modpacks. Supports version string format X.Y.Z and various parameters. Requires authentication.

```HTTP
POST /api/v1/projects/{id}/versions
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="versionNumber"

1.0.0
--boundary
Content-Disposition: form-data; name="gameVersions"

["1.19.2"]
--boundary
Content-Disposition: form-data; name="channel"

RELEASE
--boundary
Content-Disposition: form-data; name="file"; filename="mod.zip"
Content-Type: application/zip

<binary data>
```

--------------------------------

### Create Organization API

Source: https://modtale.net/api-docs/index

Creates a new organization with a specified name. Requires authentication and a JSON request body.

```HTTP
POST /api/v1/orgs
Content-Type: application/json

{
  "name": "MyStudio"
}
```

--------------------------------

### Update Project Metadata (API)

Source: https://modtale.net/api-docs/index

Updates the metadata for an existing project. This includes fields like title, description, tags, license, and repository URL. Validation rules apply to description length and repository URL format.

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

--------------------------------

### Upload Project Banner API

Source: https://modtale.net/api-docs/index

Uploads a project banner with specific validation rules for aspect ratio (3:1) and formats (PNG, JPEG, WebP). Requires authentication and a multipart file upload.

```HTTP
PUT /api/v1/projects/{id}/banner
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="banner.jpg"
Content-Type: image/jpeg

<binary data>
```

--------------------------------

### Retrieve Allowed Project Tags (API)

Source: https://modtale.net/api-docs/index

Fetches the strictly enforced list of allowed project tags. These tags are essential for search filtering and for use when creating or updating projects.

```json
[
  "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"
]
```

--------------------------------

### Unlist Project API

Source: https://modtale.net/api-docs/index

Hides a project from search results while keeping it accessible via a direct link. Requires authentication.

```HTTP
POST /api/v1/projects/{id}/unlist
```

--------------------------------

### Add Gallery Image API

Source: https://modtale.net/api-docs/index

Adds an image to a project's gallery. Requires authentication and a multipart file upload.

```HTTP
POST /api/v1/projects/{id}/gallery
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="gallery_image.webp"
Content-Type: image/webp

<binary data>
```

--------------------------------

### Organizations

Source: https://modtale.net/api-docs/index

Endpoints for creating, managing, and listing organizations and their members.

```APIDOC
## POST /api/v1/orgs

### Description
Create a new Organization.

### Method
POST

### Endpoint
/api/v1/orgs

### Parameters
#### Request Body
- **name** (string) - Required - The name of the organization.

### Request Example
```json
{
  "name": "MyStudio"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the organization.
- **username** (string) - The username of the organization.
- **accountType** (string) - The type of account (ORGANIZATION).
- **organizationMembers** (array) - A list of organization members and their roles.
  - **userId** (string) - The user's ID.
  - **role** (string) - The user's role within the organization (e.g., ADMIN).

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

```APIDOC
## GET /api/v1/user/orgs

### Description
List all organizations the authenticated user belongs to.

### Method
GET

### Endpoint
/api/v1/user/orgs

### Response
#### Success Response (200)
- **organizations** (array) - A list of organizations the user is a member of.
  - **id** (string) - The organization's ID.
  - **username** (string) - The organization's username.
  - **role** (string) - The user's role within the organization.

#### Response Example
```json
[ { "id": "...", "username": "MyStudio", "role": "ADMIN" } ]
```
```

```APIDOC
## GET /api/v1/orgs/{username}/members

### Description
Get a list of public members of a specific organization.

### Method
GET

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

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the organization.

### Response
#### Success Response (200)
- **members** (array) - A list of public members of the organization.
  - **username** (string) - The member's username.
  - **roles** (array) - The roles the member holds in the organization.
  - **avatarUrl** (string) - The URL of the member's avatar.

#### Response Example
```json
[ { "username": "User1", "roles": ["ADMIN"], "avatarUrl": "..." } ]
```
```

```APIDOC
## POST /api/v1/orgs/{id}/members

### Description
Invite a user to join an organization. This action can only be performed by an organization administrator.

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the organization.
#### Request Body
- **username** (string) - Required - The username of the user to invite.
- **role** (string) - Required - The role to assign to the invited user (e.g., MEMBER, ADMIN).

### Request Example
```json
{
  "username": "NewMember",
  "role": "MEMBER"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## PUT /api/v1/orgs/{id}/members/{userId}

### Description
Update the role of a member within an organization.

### Method
PUT

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the organization.
- **userId** (string) - Required - The unique identifier of the member whose role is to be updated.
#### Request Body
- **role** (string) - Required - The new role to assign to the member (e.g., ADMIN, MEMBER).

### Request Example
```json
{
  "role": "ADMIN"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## DELETE /api/v1/orgs/{id}/members/{userId}

### Description
Remove a member from an organization or allow a member to leave the organization.

### Method
DELETE

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the organization.
- **userId** (string) - Required - The unique identifier of the member to remove or the user's own ID to leave.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

```APIDOC
## PUT /api/v1/orgs/{id}

### Description
Update the profile information of an organization.

### Method
PUT

### Endpoint
/api/v1/orgs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the organization.
#### Request Body
- **(Fields for organization profile update)** - The fields to update (e.g., description, logo URL, etc.).

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
200 OK
```
```

--------------------------------

### Retrieve Allowed Project Classifications (API)

Source: https://modtale.net/api-docs/index

Retrieves the list of allowed project types. These classifications are used when creating or categorizing projects within the repository.

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

--------------------------------

### Delete Project API

Source: https://modtale.net/api-docs/index

Deletes a project. If the project is a dependency for other active projects, it will be soft-deleted. Otherwise, it is permanently purged. Requires authentication.

```HTTP
DELETE /api/v1/projects/{id}
```

--------------------------------

### Invite Contributor API

Source: https://modtale.net/api-docs/index

Invites a user to collaborate on an individual project. Requires authentication.

```HTTP
POST /api/v1/projects/{id}/invite?username=ContributorUsername
```

--------------------------------

### User Profile & Settings API

Source: https://modtale.net/api-docs/index

Endpoints for retrieving and updating user profile information, avatar, banner, and notification preferences, as well as following/unfollowing users and account deletion.

```APIDOC
## GET /api/v1/user/me

### Description
Get authenticated user details.

### Method
GET

### Endpoint
/api/v1/user/me

### Response
#### Success Response (200)
- **id** (string) - The user's unique identifier.
- **username** (string) - The user's username.
- **email** (string) - The user's email address.
- **roles** (array of strings) - The roles assigned to the user.
- **tier** (string) - The user's subscription tier (e.g., "FREE").
- **likedModIds** (array of strings) - IDs of mods the user has liked.
- **followingIds** (array of strings) - IDs of users the user is following.
- **notificationPreferences** (object) - User's notification settings.

### Response Example
```json
{
  "id": "u1",
  "username": "Me",
  "email": "me@example.com",
  "roles": ["ROLE_USER"],
  "tier": "FREE",
  "likedModIds": ["m1", "m2"],
  "followingIds": ["u2"],
  "notificationPreferences": { ... }
}
```
```

```APIDOC
## PUT /api/v1/user/profile

### Description
Update profile settings.

### Method
PUT

### Endpoint
/api/v1/user/profile

### Parameters
#### Request Body (application/json)
- **username** (string) - Optional - The new username for the user.
- **bio** (string) - Optional - The new biography for the user.

### Request Example
```json
{
  "username": "NewName",
  "bio": "I make things."
}
```

### Response
#### Success Response (200)
- **updatedUser** (object) - The updated user object.

### Response Example
```json
{ ...updatedUser }
```
```

```APIDOC
## POST /api/v1/user/profile/avatar

### Description
Upload user avatar.

### Method
POST

### Endpoint
/api/v1/user/profile/avatar

### Parameters
#### Form Parameters
- **file** (multipart/form-data) - Required - The avatar image file.

### Response
#### Success Response (200)
- **url** (string) - The URL of the uploaded avatar.

### Response Example
```
"url"
```
```

```APIDOC
## POST /api/v1/user/profile/banner

### Description
Upload user banner.

### Method
POST

### Endpoint
/api/v1/user/profile/banner

### Parameters
#### Form Parameters
- **file** (multipart/form-data) - Required - The banner image file.

### Response
#### Success Response (200)
- **url** (string) - The URL of the uploaded banner.

### Response Example
```
"url"
```
```

```APIDOC
## PUT /api/v1/user/settings/notifications

### Description
Update notification preferences.

### Method
PUT

### Endpoint
/api/v1/user/settings/notifications

### Parameters
#### Request Body (application/json)
- **projectUpdates** (string) - Optional - Notification setting for project updates (e.g., "EMAIL", "OFF").
- **newFollowers** (string) - Optional - Notification setting for new followers (e.g., "ON", "OFF").
- **dependencyUpdates** (string) - Optional - Notification setting for dependency updates (e.g., "EMAIL", "OFF").
- **creatorUploads** (string) - Optional - Notification setting for creator uploads (e.g., "ON", "OFF").

### Request Example
```json
{
  "projectUpdates": "EMAIL",
  "newFollowers": "ON",
  "dependencyUpdates": "OFF",
  "creatorUploads": "ON"
}
```

### Response
#### Success Response (200)
- **Status**: 200 OK

### Response Example
```
200 OK
```
```

```APIDOC
## POST /api/v1/user/follow/{targetUsername}

### Description
Follow a user.

### Method
POST

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

### Parameters
#### Path Parameters
- **targetUsername** (string) - Required - The username of the user to follow.

### Response
#### Success Response (200)
- **Status**: 200 OK

### Response Example
```
200 OK
```
```

```APIDOC
## POST /api/v1/user/unfollow/{targetUsername}

### Description
Unfollow a user.

### Method
POST

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

### Parameters
#### Path Parameters
- **targetUsername** (string) - Required - The username of the user to unfollow.

### Response
#### Success Response (200)
- **Status**: 200 OK

### Response Example
```
200 OK
```
```

```APIDOC
## DELETE /api/v1/user/me

### Description
Permanently delete user account.

### Method
DELETE

### Endpoint
/api/v1/user/me

### Response
#### Success Response (200)
- **Status**: 200 OK

### Response Example
```
200 OK
```
```

--------------------------------

### Decline Contribution Invite API

Source: https://modtale.net/api-docs/index

Declines an invitation to contribute to a project. Requires authentication.

```HTTP
POST /api/v1/projects/{id}/invite/decline
```

--------------------------------

### Archive Project (API)

Source: https://modtale.net/api-docs/index

Archives a project, making it read-only while still visible. This endpoint is used to manage the lifecycle of projects that are no longer actively developed but should remain accessible.

```http
POST /api/v1/projects/{id}/archive
```

--------------------------------

### Resolve Ownership Transfer API

Source: https://modtale.net/api-docs/index

Accepts or declines a pending project ownership transfer request. Requires authentication and a JSON request body indicating acceptance.

```HTTP
POST /api/v1/projects/{id}/transfer/resolve
Content-Type: application/json

{
  "accept": true
}
```

--------------------------------

### Mark All Notifications as Read

Source: https://modtale.net/api-docs/index

Marks all notifications for the authenticated user as read. This is a POST request to the /read-all endpoint.

```http
POST /api/v1/notifications/read-all
```

--------------------------------

### Delete Project Version API

Source: https://modtale.net/api-docs/index

Deletes a specific version of a project. This is prevented if the version is the only one for a published project. Requires authentication.

```HTTP
DELETE /api/v1/projects/{id}/versions/{versionId}
```

--------------------------------

### Social Actions API

Source: https://modtale.net/api-docs/index

Endpoints for performing social actions such as favoriting projects and posting reviews.

```APIDOC
## POST /api/v1/projects/{id}/favorite

### Description
Toggle favorite status for a project.

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **Status**: 200 OK

### Response Example
```
200 OK
```
```

```APIDOC
## POST /api/v1/projects/{id}/reviews

### Description
Post a review for a project.

### Method
POST

### Endpoint
/api/v1/projects/{id}/reviews

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
#### Request Body (application/json)
- **rating** (integer) - Required - The rating given to the project (e.g., 1-5).
- **comment** (string) - Optional - The text comment for the review.
- **version** (string) - Optional - The version of the project the review is for.

### Request Example
```json
{
  "rating": 5,
  "comment": "Amazing mod!",
  "version": "1.0.0"
}
```

### Response
#### Success Response (200)
- **Status**: 200 OK

### Response Example
```
200 OK
```
```
Tokens:
Raw