-
Notifications
You must be signed in to change notification settings - Fork 48
/
openapi.yaml
3882 lines (3818 loc) · 131 KB
/
openapi.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: '3.0.0'
info:
version: v2.7.0/15cf3fc
title: Labrinth
termsOfService: https://modrinth.com/legal/terms
contact:
name: Modrinth Support
url: https://support.modrinth.com
email: support@modrinth.com
description: |
This documentation doesn't provide a way to test our API. In order to facilitate testing, we recommend the following tools:
- [cURL](https://curl.se/) (recommended, command-line)
- [ReqBIN](https://reqbin.com/) (recommended, online)
- [Postman](https://www.postman.com/downloads/)
- [Insomnia](https://insomnia.rest/)
- Your web browser, if you don't need to send headers or a request body
Once you have a working client, you can test that it works by making a `GET` request to `https://staging-api.modrinth.com/`:
```json
{
"about": "Welcome traveler!",
"documentation": "https://docs.modrinth.com",
"name": "modrinth-labrinth",
"version": "2.7.0"
}
```
If you got a response similar to the one above, you can use the Modrinth API!
When you want to go live using the production API, use `api.modrinth.com` instead of `staging-api.modrinth.com`.
## Authentication
This API has two options for authentication: personal access tokens and [OAuth2](https://en.wikipedia.org/wiki/OAuth).
All tokens are tied to a Modrinth user and use the `Authorization` header of the request.
Example:
```
Authorization: mrp_RNtLRSPmGj2pd1v1ubi52nX7TJJM9sznrmwhAuj511oe4t1jAqAQ3D6Wc8Ic
```
You do not need a token for most requests. Generally speaking, only the following types of requests require a token:
- those which create data (such as version creation)
- those which modify data (such as editing a project)
- those which access private data (such as draft projects, notifications, emails, and payout data)
Each request requiring authentication has a certain scope. For example, to view the email of the user being requested, the token must have the `USER_READ_EMAIL` scope.
You can find the list of available scopes [on GitHub](https://github.com/modrinth/labrinth/blob/master/src/models/pats.rs#L15). Making a request with an invalid scope will return a 401 error.
Please note that certain scopes and requests cannot be completed with a personal access token or using OAuth.
For example, deleting a user account can only be done through Modrinth's frontend.
### OAuth2
Applications interacting with the authenticated API should create an OAuth2 application.
You can do this in [the developer settings](https://modrinth.com/settings/applications).
Once you have created a client, use the following URL to have a user authorize your client:
```
https://modrinth.com/auth/authorize?client_id=<CLIENT_ID>&redirect_uri=<CALLBACK_URL>&scope=<SCOPE_ONE>+<SCOPE_TWO>+<SCOPE_THREE>
```
Then, use the following URL to get the token:
```
https://api.modrinth.com/_internal/oauth/token
```
This route will be changed in the future to move the `_internal` part to `v3`.
### Personal access tokens
Personal access tokens (PATs) can be generated in from [the user settings](https://modrinth.com/settings/account).
### GitHub tokens
For backwards compatibility purposes, some types of GitHub tokens also work for authenticating a user with Modrinth's API, granting all scopes.
**We urge any application still using GitHub tokens to start using personal access tokens for security and reliability purposes.**
GitHub tokens will cease to function to authenticate with Modrinth's API as soon as version 3 of the API is made generally available.
## Cross-Origin Resource Sharing
This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with the [W3C spec](https://www.w3.org/TR/cors/).
This allows for cross-domain communication from the browser.
All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.
## Identifiers
The majority of items you can interact with in the API have a unique eight-digit base62 ID.
Projects, versions, users, threads, teams, and reports all use this same way of identifying themselves.
Version files use the sha1 or sha512 file hashes as identifiers.
Each project and user has a friendlier way of identifying them; slugs and usernames, respectively.
While unique IDs are constant, slugs and usernames can change at any moment.
If you want to store something in the long term, it is recommended to use the unique ID.
## Ratelimits
The API has a ratelimit defined per IP. Limits and remaining amounts are given in the response headers.
- `X-Ratelimit-Limit`: the maximum number of requests that can be made in a minute
- `X-Ratelimit-Remaining`: the number of requests remaining in the current ratelimit window
- `X-Ratelimit-Reset`: the time in seconds until the ratelimit window resets
Ratelimits are the same no matter whether you use a token or not.
The ratelimit is currently 300 requests per minute. If you have a use case requiring a higher limit, please [contact us](mailto:admin@modrinth.com).
## User Agents
To access the Modrinth API, you **must** use provide a uniquely-identifying `User-Agent` header.
Providing a user agent that only identifies your HTTP client library (such as "okhttp/4.9.3") increases the likelihood that we will block your traffic.
It is recommended, but not required, to include contact information in your user agent.
This allows us to contact you if we would like a change in your application's behavior without having to block your traffic.
- Bad: `User-Agent: okhttp/4.9.3`
- Good: `User-Agent: project_name`
- Better: `User-Agent: github_username/project_name/1.56.0`
- Best: `User-Agent: github_username/project_name/1.56.0 (launcher.com)` or `User-Agent: github_username/project_name/1.56.0 (contact@launcher.com)`
## Versioning
Modrinth follows a simple pattern for its API versioning.
In the event of a breaking API change, the API version in the URL path is bumped, and migration steps will be published below.
When an API is no longer the current one, it will immediately be considered deprecated.
No more support will be provided for API versions older than the current one.
It will be kept for some time, but this amount of time is not certain.
We will exercise various tactics to get people to update their implementation of our API.
One example is by adding something like `STOP USING THIS API` to various data returned by the API.
Once an API version is completely deprecated, it will permanently return a 410 error.
Please ensure your application handles these 410 errors.
### Migrations
Inside the following spoiler, you will be able to find all changes between versions of the Modrinth API, accompanied by tips and a guide to migrate applications to newer versions.
Here, you can also find changes for [Minotaur](https://github.com/modrinth/minotaur), Modrinth's official Gradle plugin. Major versions of Minotaur directly correspond to major versions of the Modrinth API.
<details><summary>API v1 to API v2</summary>
These bullet points cover most changes in the v2 API, but please note that fields containing `mod` in most contexts have been shifted to `project`. For example, in the search route, the field `mod_id` was renamed to `project_id`.
- The search route has been moved from `/api/v1/mod` to `/v2/search`
- New project fields: `project_type` (may be `mod` or `modpack`), `moderation_message` (which has a `message` and `body`), `gallery`
- New search facet: `project_type`
- Alphabetical sort removed (it didn't work and is not possible due to limits in MeiliSearch)
- New search fields: `project_type`, `gallery`
- The gallery field is an array of URLs to images that are part of the project's gallery
- The gallery is a new feature which allows the user to upload images showcasing their mod to the CDN which will be displayed on their mod page
- Internal change: Any project file uploaded to Modrinth is now validated to make sure it's a valid Minecraft mod, Modpack, etc.
- For example, a Forge 1.17 mod with a JAR not containing a mods.toml will not be allowed to be uploaded to Modrinth
- In project creation, projects may not upload a mod with no versions to review, however they can be saved as a draft
- Similarly, for version creation, a version may not be uploaded without any files
- Donation URLs have been enabled
- New project status: `archived`. Projects with this status do not appear in search
- Tags (such as categories, loaders) now have icons (SVGs) and specific project types attached
- Dependencies have been wiped and replaced with a new system
- Notifications now have a `type` field, such as `project_update`
Along with this, project subroutes (such as `/v2/project/{id}/version`) now allow the slug to be used as the ID. This is also the case with user routes.
</details><details><summary>Minotaur v1 to Minotaur v2</summary>
Minotaur 2.x introduced a few breaking changes to how your buildscript is formatted.
First, instead of registering your own `publishModrinth` task, Minotaur now automatically creates a `modrinth` task. As such, you can replace the `task publishModrinth(type: TaskModrinthUpload) {` line with just `modrinth {`.
To declare supported Minecraft versions and mod loaders, the `gameVersions` and `loaders` arrays must now be used. The syntax for these are pretty self-explanatory.
Instead of using `releaseType`, you must now use `versionType`. This was actually changed in v1.2.0, but very few buildscripts have moved on from v1.1.0.
Dependencies have been changed to a special DSL. Create a `dependencies` block within the `modrinth` block, and then use `scope.type("project/version")`. For example, `required.project("fabric-api")` adds a required project dependency on Fabric API.
You may now use the slug anywhere that a project ID was previously required.
</details>
# The above snippet about User Agents was adapted from https://crates.io/policies, copyright (c) 2014 The Rust Project Developers under MIT license
servers:
- url: https://api.modrinth.com/v2
description: Production server
- url: https://staging-api.modrinth.com/v2
description: Staging server
components:
parameters:
ProjectIdentifier:
name: id|slug
in: path
required: true
description: The ID or slug of the project
schema:
type: string
example: [AABBCCDD, my_project]
MultipleProjectIdentifier:
in: query
name: ids
description: The IDs and/or slugs of the projects
schema:
type: string
example: "[\"AABBCCDD\", \"EEFFGGHH\"]"
required: true
UserIdentifier:
name: id|username
in: path
required: true
description: The ID or username of the user
schema:
type: string
example: [EEFFGGHH, my_user]
VersionIdentifier:
name: id
in: path
required: true
description: The ID of the version
schema:
type: string
example: [IIJJKKLL]
TeamIdentifier:
name: id
in: path
required: true
description: The ID of the team
schema:
type: string
example: [MMNNOOPP]
ReportIdentifier:
name: id
in: path
required: true
description: The ID of the report
schema:
type: string
example: [RRSSTTUU]
ThreadIdentifier:
name: id
in: path
required: true
description: The ID of the thread
schema:
type: string
example: [QQRRSSTT]
NotificationIdentifier:
name: id
in: path
required: true
description: The ID of the notification
schema:
type: string
example: [NNOOPPQQ]
AlgorithmIdentifier:
name: algorithm
in: query
required: true
description: The algorithm of the hash
schema:
type: string
enum: [sha1, sha512]
example: sha512
default: sha1
MultipleHashQueryIdentifier:
name: multiple
in: query
required: false
description: Whether to return multiple results when looking for this hash
schema:
type: boolean
default: false
FileHashIdentifier:
name: hash
in: path
required: true
description: The hash of the file, considering its byte content, and encoded in hexadecimal
schema:
type: string
example: 619e250c133106bacc3e3b560839bd4b324dfda8
requestBodies:
Image:
content:
image/png:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
image/bmp:
schema:
type: string
format: binary
image/gif:
schema:
type: string
format: binary
image/webp:
schema:
type: string
format: binary
image/svg:
schema:
type: string
format: binary
image/svgz:
schema:
type: string
format: binary
image/rgb:
schema:
type: string
format: binary
schemas:
# Version
BaseVersion:
type: object
properties:
name:
type: string
description: The name of this version
example: "Version 1.0.0"
version_number:
type: string
description: "The version number. Ideally will follow semantic versioning"
example: "1.0.0"
changelog:
type: string
description: "The changelog for this version"
example: "List of changes in this version: ..."
nullable: true
dependencies:
type: array
items:
$ref: "#/components/schemas/VersionDependency"
description: A list of specific versions of projects that this version depends on
game_versions:
type: array
items:
type: string
description: A list of versions of Minecraft that this version supports
example: ["1.16.5", "1.17.1"]
version_type:
type: string
description: The release channel for this version
enum: [release, beta, alpha]
example: release
loaders:
type: array
items:
type: string
description: The mod loaders that this version supports
example: ["fabric", "forge"]
featured:
type: boolean
description: Whether the version is featured or not
example: true
status:
type: string
enum: [listed, archived, draft, unlisted, scheduled, unknown]
example: listed
requested_status:
type: string
enum: [listed, archived, draft, unlisted]
nullable: true
VersionDependency:
type: object
properties:
version_id:
type: string
description: The ID of the version that this version depends on
example: IIJJKKLL
nullable: true
project_id:
type: string
description: The ID of the project that this version depends on
example: QQRRSSTT
nullable: true
file_name:
type: string
description: The file name of the dependency, mostly used for showing external dependencies on modpacks
example: sodium-fabric-mc1.19-0.4.2+build.16.jar
nullable: true
dependency_type:
type: string
enum: [ required, optional, incompatible, embedded ]
description: The type of dependency that this version has
example: required
required:
- dependency_type
# https://github.com/modrinth/labrinth/blob/master/src/routes/versions.rs#L169-L190
EditableVersion:
allOf:
- $ref: '#/components/schemas/BaseVersion'
- type: object
properties:
primary_file:
type: array
items:
type: string
example: [sha1, aaaabbbbccccddddeeeeffffgggghhhhiiiijjjj]
description: The hash format and the hash of the new primary file
file_types:
type: array
items:
$ref: '#/components/schemas/EditableFileType'
description: A list of file_types to edit
EditableFileType:
type: object
properties:
algorithm:
type: string
description: The hash algorithm of the hash specified in the hash field
example: sha1
hash:
type: string
description: The hash of the file you're editing
example: aaaabbbbccccddddeeeeffffgggghhhhiiiijjjj
file_type:
type: string
enum: [ required-resource-pack, optional-resource-pack ]
description: The hash algorithm of the file you're editing
example: required-resource-pack
nullable: true
required:
- algorithm
- hash
- file_type
# https://github.com/modrinth/labrinth/blob/master/src/routes/version_creation.rs#L27-L57
CreatableVersion:
allOf:
- $ref: '#/components/schemas/BaseVersion'
- type: object
properties:
project_id:
type: string
description: The ID of the project this version is for
example: AABBCCDD
file_parts:
type: array
items:
type: string
description: An array of the multipart field names of each file that goes with this version
primary_file:
type: string
description: The multipart field name of the primary file
required:
- file_parts
- project_id
- name
- version_number
- game_versions
- version_type
- loaders
- featured
- dependencies
CreateVersionBody:
type: object
properties:
data:
$ref: '#/components/schemas/CreatableVersion'
required: [ data ]
Version:
allOf:
- $ref: '#/components/schemas/BaseVersion'
- type: object
properties:
id:
type: string
description: The ID of the version, encoded as a base62 string
example: IIJJKKLL
project_id:
type: string
description: The ID of the project this version is for
example: AABBCCDD
author_id:
type: string
description: The ID of the author who published this version
example: EEFFGGHH
date_published:
type: string
format: ISO-8601
downloads:
type: integer
description: The number of times this version has been downloaded
changelog_url:
type: string
description: A link to the changelog for this version. Always null, only kept for legacy compatibility.
deprecated: true
example: null
nullable: true
files:
type: array
items:
$ref: '#/components/schemas/VersionFile'
description: A list of files available for download for this version
required:
- id
- project_id
- author_id
- date_published
- downloads
- files
- name
- version_number
- game_versions
- version_type
- loaders
- featured
VersionFile:
type: object
properties:
hashes:
$ref: '#/components/schemas/VersionFileHashes'
url:
type: string
example: "https://cdn.modrinth.com/data/AABBCCDD/versions/1.0.0/my_file.jar"
description: A direct link to the file
filename:
type: string
example: "my_file.jar"
description: The name of the file
primary:
type: boolean
example: false
description: Whether this file is the primary one for its version. Only a maximum of one file per version will have this set to true. If there are not any primary files, it can be inferred that the first file is the primary one.
size:
type: integer
example: 1097270
description: The size of the file in bytes
file_type:
type: string
enum: [ required-resource-pack, optional-resource-pack ]
description: The type of the additional file, used mainly for adding resource packs to datapacks
example: required-resource-pack
nullable: true
required:
- hashes
- url
- filename
- primary
- size
VersionFileHashes:
type: object
properties:
sha512:
type: string
example: 93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f
sha1:
type: string
example: c84dd4b3580c02b79958a0590afd5783d80ef504
description: A map of hashes of the file. The key is the hashing algorithm and the value is the string version of the hash.
GetLatestVersionFromHashBody:
type: object
properties:
loaders:
type: array
items:
type: string
example: [ fabric ]
game_versions:
type: array
items:
type: string
example: [ "1.18", 1.18.1 ]
required:
- loaders
- game_versions
HashVersionMap:
description: "A map from hashes to versions"
type: object
additionalProperties:
$ref: '#/components/schemas/Version'
HashList:
description: "A list of hashes and the algorithm used to create them"
type: object
properties:
hashes:
type: array
items:
type: string
example: [ ea0f38408102e4d2efd53c2cc11b88b711996b48d8922f76ea6abf731219c5bd1efe39ddf9cce77c54d49a62ff10fb685c00d2e4c524ab99d20f6296677ab2c4, 925a5c4899affa4098d997dfa4a4cb52c636d539e94bc489d1fa034218cb96819a70eb8b01647a39316a59fcfe223c1a8c05ed2e2ae5f4c1e75fa48f6af1c960 ]
algorithm:
type: string
enum: [ sha1, sha512 ]
example: sha512
required:
- hashes
- algorithm
GetLatestVersionsFromHashesBody:
allOf:
- $ref: '#/components/schemas/HashList'
- type: object
properties:
loaders:
type: array
items:
type: string
example: [ fabric ]
game_versions:
type: array
items:
type: string
example: [ "1.18", 1.18.1 ]
required:
- loaders
- game_versions
# Project
# Fields that can be used in everything. Search, direct project lookup, project editing, you name it.
BaseProject:
type: object
properties:
slug:
type: string
description: "The slug of a project, used for vanity URLs. Regex: ```^[\\w!@$()`.+,\"\\-']{3,64}$```"
example: my_project
title:
type: string
description: The title or name of the project
example: My Project
description:
type: string
description: A short description of the project
example: A short description
categories:
type: array
items:
type: string
example: [technology, adventure, fabric]
description: A list of the categories that the project has
client_side:
type: string
enum: [required, optional, unsupported]
description: The client side support of the project
example: required
server_side:
type: string
enum: [required, optional, unsupported]
description: The server side support of the project
example: optional
# Fields added to search results and direct project lookups that cannot be edited.
ServerRenderedProject:
allOf:
- $ref: '#/components/schemas/BaseProject'
- type: object
properties:
project_type:
type: string
enum: [mod, modpack, resourcepack, shader]
description: The project type of the project
example: mod
downloads:
type: integer
description: The total number of downloads of the project
icon_url:
type: string
example: https://cdn.modrinth.com/data/AABBCCDD/b46513nd83hb4792a9a0e1fn28fgi6090c1842639.png
description: The URL of the project's icon
nullable: true
color:
type: integer
example: 8703084
description: The RGB color of the project, automatically generated from the project icon
nullable: true
thread_id:
type: string
example: TTUUVVWW
description: The ID of the moderation thread associated with this project
monetization_status:
type: string
enum: [monetized, demonetized, force-demonetized]
required:
- project_type
- downloads
# The actual result in search.
ProjectResult:
allOf:
- $ref: '#/components/schemas/ServerRenderedProject'
- type: object
properties:
project_id:
type: string
description: The ID of the project
example: AABBCCDD
author:
type: string
description: The username of the project's author
example: my_user
display_categories:
type: array
items:
type: string
description: A list of the categories that the project has which are not secondary
example: ["technology", "fabric"]
versions:
type: array
items:
type: string
description: A list of the minecraft versions supported by the project
example: ["1.8", "1.8.9"]
follows:
type: integer
description: The total number of users following the project
date_created:
type: string
format: ISO-8601
description: The date the project was added to search
date_modified:
type: string
format: ISO-8601
description: The date the project was last modified
latest_version:
type: string
description: The latest version of minecraft that this project supports
example: 1.8.9
license:
type: string
description: The SPDX license ID of a project
example: MIT
gallery:
type: array
description: All gallery images attached to the project
example: [https://cdn.modrinth.com/data/AABBCCDD/images/009b7d8d6e8bf04968a29421117c59b3efe2351a.png, https://cdn.modrinth.com/data/AABBCCDD/images/c21776867afb6046fdc3c21dbcf5cc50ae27a236.png]
items:
type: string
featured_gallery:
type: string
description: The featured gallery image of the project
nullable: true
required:
- slug
- title
- description
- client_side
- server_side
- project_id
- author
- versions
- follows
- date_created
- date_modified
- license
# Fields that appear everywhere EXCEPT search.
NonSearchProject:
allOf:
- $ref: '#/components/schemas/BaseProject'
- type: object
properties:
body:
type: string
description: A long form description of the project
example: A long body describing my project in detail
status:
type: string
enum: [approved, archived, rejected, draft, unlisted, processing, withheld, scheduled, private, unknown]
description: The status of the project
example: approved
requested_status:
type: string
enum: [approved, archived, unlisted, private, draft]
description: The requested status when submitting for review or scheduling the project for release
nullable: true
additional_categories:
type: array
items:
type: string
description: A list of categories which are searchable but non-primary
example: [technology, adventure, fabric]
issues_url:
type: string
description: An optional link to where to submit bugs or issues with the project
example: https://github.com/my_user/my_project/issues
nullable: true
source_url:
type: string
description: An optional link to the source code of the project
example: https://github.com/my_user/my_project
nullable: true
wiki_url:
type: string
description: An optional link to the project's wiki page or other relevant information
example: https://github.com/my_user/my_project/wiki
nullable: true
discord_url:
type: string
description: An optional invite link to the project's discord
example: https://discord.gg/AaBbCcDd
nullable: true
donation_urls:
type: array
items:
$ref: '#/components/schemas/ProjectDonationURL'
description: A list of donation links for the project
ProjectDonationURL:
type: object
properties:
id:
type: string
description: The ID of the donation platform
example: patreon
platform:
type: string
description: The donation platform this link is to
example: Patreon
url:
type: string
description: The URL of the donation platform and user
example: https://www.patreon.com/my_user
# Fields available only when editing or creating a project
ModifiableProject:
allOf:
- $ref: '#/components/schemas/NonSearchProject'
- type: object
properties:
license_id:
type: string
description: The SPDX license ID of a project
example: LGPL-3.0-or-later
license_url:
type: string
description: The URL to this license
nullable: true
# Fields that can be edited through a PATCH request. https://github.com/modrinth/labrinth/blob/master/src/routes/projects.rs#L195-L269
EditableProject:
allOf:
- $ref: '#/components/schemas/ModifiableProject'
- type: object
properties:
moderation_message:
type: string
description: The title of the moderators' message for the project
nullable: true
moderation_message_body:
type: string
description: The body of the moderators' message for the project
nullable: true
# Fields only available for project creation. https://github.com/modrinth/labrinth/blob/master/src/routes/project_creation.rs#L129-L197
CreatableProject:
allOf:
- $ref: '#/components/schemas/ModifiableProject'
- type: object
properties:
project_type:
type: string
enum: [mod, modpack]
example: modpack
initial_versions:
type: array
items:
$ref: '#/components/schemas/EditableVersion'
description: A list of initial versions to upload with the created project. Deprecated - please upload version files after initial upload.
deprecated: true
is_draft:
type: boolean
description: Whether the project should be saved as a draft instead of being sent to moderation for review. Deprecated - please always mark this as true.
example: true
deprecated: true
gallery_items:
type: array
description: Gallery images to be uploaded with the created project. Deprecated - please upload gallery images after initial upload.
deprecated: true
items:
$ref: '#/components/schemas/CreatableProjectGalleryItem'
required:
- project_type
- slug
- title
- description
- body
- categories
- client_side
- server_side
- license_id
CreatableProjectGalleryItem:
type: object
nullable: true
properties:
item:
type: string
description: The name of the multipart item where the gallery media is located
featured:
type: boolean
description: Whether the image is featured in the gallery
example: true
title:
type: string
description: The title of the gallery image
example: My awesome screenshot!
nullable: true
description:
type: string
description: The description of the gallery image
example: This awesome screenshot shows all of the blocks in my mod!
nullable: true
ordering:
type: integer
description: The order of the gallery image. Gallery images are sorted by this field and then alphabetically by title.
example: 0
Project:
allOf:
- $ref: '#/components/schemas/NonSearchProject'
- $ref: '#/components/schemas/ServerRenderedProject'
- type: object
properties:
id:
type: string
example: AABBCCDD
description: The ID of the project, encoded as a base62 string
team:
type: string
example: MMNNOOPP
description: The ID of the team that has ownership of this project
body_url:
type: string
deprecated: true
default: null
description: The link to the long description of the project. Always null, only kept for legacy compatibility.
example: null
nullable: true
moderator_message:
$ref: '#/components/schemas/ModeratorMessage'
published:
type: string
format: ISO-8601
description: The date the project was published
updated:
type: string
format: ISO-8601
description: The date the project was last updated
approved:
type: string
format: ISO-8601
description: The date the project's status was set to an approved status
nullable: true
queued:
type: string
format: ISO-8601
description: The date the project's status was submitted to moderators for review
nullable: true
followers:
type: integer
description: The total number of users following the project
license:
$ref: '#/components/schemas/ProjectLicense'
versions:
type: array
items:
type: string
example: [IIJJKKLL, QQRRSSTT]
description: A list of the version IDs of the project (will never be empty unless `draft` status)
game_versions:
type: array
items:
type: string
example: ["1.19", "1.19.1", "1.19.2", "1.19.3"]
description: A list of all of the game versions supported by the project
loaders:
type: array
items:
type: string
example: ["forge", "fabric", "quilt"]
description: A list of all of the loaders supported by the project
gallery:
type: array
items:
$ref: '#/components/schemas/GalleryImage'
description: A list of images that have been uploaded to the project's gallery
required:
- id
- team
- published
- updated
- followers
- title
- description
- categories
- client_side
- server_side
- slug
- body
- status
ModeratorMessage:
deprecated: true
type: object
properties:
message:
type: string
description: The message that a moderator has left for the project
body:
type: string
description: The longer body of the message that a moderator has left for the project
nullable: true
nullable: true
example: null
description: A message that a moderator sent regarding the project
ProjectLicense:
type: object
properties:
id:
type: string
description: The SPDX license ID of a project
example: LGPL-3.0-or-later
name:
type: string
description: The long name of a license
example: GNU Lesser General Public License v3 or later
url:
type: string
description: The URL to this license