Skip to main content
Organizations are groups of users that can collectively own and manage multiple projects. When a project belongs to an organization, all organization members inherit permissions to manage that project.

​
Get Organization

Retrieve a single organization by its ID or slug. 
GET /v3/organization/{id}

​
Path Parameters

​
id
string
required
The organization ID or slug

​
Response

​
id
string
The organization’s unique ID
​
slug
string
The organization’s URL-safe slug
​
name
string
The organization’s name/title
​
description
string
The organization’s description
​
team_id
string
The ID of the organization’s team
​
icon_url
string
URL to the organization’s icon
​
color
integer
Primary color extracted from the icon (as RGB integer)
​
members
array
Array of team members

​
Example Request

curl https://api.modrinth.com/v3/organization/my-org

​
Example Response

{
  "id": "aBcDeFgH",
  "slug": "my-org",
  "name": "My Organization",
  "description": "A group of developers creating amazing mods",
  "team_id": "xYz12345",
  "icon_url": "https://cdn.modrinth.com/data/aBcDeFgH/icon.png",
  "color": 5814783,
  "members": [
    {
      "user": {
        "id": "9dU94F4T",
        "username": "jellysquid",
        "avatar_url": "https://cdn.modrinth.com/avatars/9dU94F4T.png"
      },
      "role": "Owner",
      "permissions": 255,
      "organization_permissions": 255,
      "accepted": true,
      "payouts_split": 10000,
      "ordering": 0
    }
  ]
}

​
Get Multiple Organizations

Retrieve multiple organizations by their IDs or slugs. 
GET /v3/organizations?ids=["id1","id2"]

​
Query Parameters

​
ids
string
required
JSON array of organization IDs or slugs as a string

​
Example Request

curl 'https://api.modrinth.com/v3/organizations?ids=["org1","org2"]'

​
Create Organization

Create a new organization. Requires authentication and ORGANIZATION_CREATE scope. 
POST /v3/organization

​
Request Body

​
slug
string
required
URL-safe organization slug (3-64 characters, lowercase letters, numbers, hyphens)
​
name
string
required
Organization name/title (3-64 characters)
​
description
string
required
Organization description (3-256 characters)

​
Response

Returns the newly created organization object with the creator as the owner.

​
Example Request

curl -X POST https://api.modrinth.com/v3/organization \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "awesome-devs",
    "name": "Awesome Developers",
    "description": "Building the future of Minecraft modding"
  }'

​
Limits

Users have a limit on the number of organizations they can create. If the limit is reached, the request will fail with a LimitReached error.

​
Edit Organization

Update an organization’s details. Requires authentication and ORGANIZATION_WRITE scope with EDIT_DETAILS permission. 
PATCH /v3/organization/{id}

​
Path Parameters

​
id
string
required
The organization ID or slug

​
Request Body

​
name
string
New organization name (3-64 characters)
​
slug
string
New URL-safe slug (3-64 characters)
​
description
string
New organization description (3-256 characters)

​
Example Request

curl -X PATCH https://api.modrinth.com/v3/organization/my-org \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "An updated organization description"
  }'

​
Notes

  • Slug changes must not collide with existing organization IDs or slugs
  • Returns 204 No Content on success
  • Requires EDIT_DETAILS organization permission

​
Delete Organization

Delete an organization. Requires authentication and ORGANIZATION_DELETE scope with DELETE_ORGANIZATION permission. 
DELETE /v3/organization/{id}

​
Path Parameters

​
id
string
required
The organization ID or slug

​
Behavior

When an organization is deleted:
  • All projects owned by the organization are transferred to the organization owner
  • The organization owner becomes the “Inherited Owner” of each project
  • Organization members are removed from project teams
  • The organization and its team are permanently deleted

​
Example Request

curl -X DELETE https://api.modrinth.com/v3/organization/my-org \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get Organization Projects

List all projects owned by an organization. 
GET /v3/organization/{id}/projects

​
Path Parameters

​
id
string
required
The organization ID or slug

​
Response

Returns an array of project objects owned by the organization. Only includes projects visible to the requesting user.

​
Example Request

curl https://api.modrinth.com/v3/organization/my-org/projects

​
Example Response

[
  {
    "id": "AANobbMI",
    "slug": "sodium",
    "name": "Sodium",
    "summary": "A modern rendering engine",
    "organization_id": "aBcDeFgH",
    "team_id": "3vHspAEn",
    "status": "approved",
    "downloads": 50000000
  }
]

​
Add Project to Organization

Add an existing project to an organization. Requires authentication and both PROJECT_WRITE and ORGANIZATION_WRITE scopes. 
POST /v3/organization/{id}/projects

​
Path Parameters

​
id
string
required
The organization ID or slug

​
Request Body

​
project_id
string
required
The project ID or slug to add

​
Requirements

  • You must be an owner of the project you’re adding
  • You must have ADD_PROJECT permission in the organization
  • The project must not already belong to another organization

​
Behavior

When a project is added to an organization:
  • The project’s organization_id is set
  • Former project owners lose their owner status
  • The organization owner is removed from the project team
  • Organization members inherit permissions to the project

​
Example Request

curl -X POST https://api.modrinth.com/v3/organization/my-org/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "sodium"
  }'

​
Remove Project from Organization

Remove a project from an organization and transfer it to a new owner. Requires authentication and both PROJECT_WRITE and ORGANIZATION_WRITE scopes. 
DELETE /v3/organization/{id}/projects/{project_id}

​
Path Parameters

​
id
string
required
The organization ID or slug
​
project_id
string
required
The project ID or slug to remove

​
Request Body

​
new_owner
string
required
User ID of the new project owner (must be an organization member)

​
Requirements

  • You must have REMOVE_PROJECT permission in the organization
  • The specified new owner must be a member of the organization
  • The project must currently be owned by the organization

​
Behavior

When a project is removed:
  • The project’s organization_id is set to null
  • The specified user becomes the project owner
  • If the new owner isn’t already a project team member, they’re added as “Inherited Owner”
  • Organization permissions are removed from the project

​
Example Request

curl -X DELETE https://api.modrinth.com/v3/organization/my-org/projects/sodium \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_owner": "9dU94F4T"
  }'

​
Get Project’s Organization

Get the organization that owns a specific project. 
GET /v3/project/{id}/organization

​
Path Parameters

​
id
string
required
The project ID or slug

​
Response

Returns the organization object if the project belongs to an organization, otherwise returns 404.

​
Example Request

curl https://api.modrinth.com/v3/project/sodium/organization

​
Update Organization Icon

Upload a new icon for the organization. Requires authentication and ORGANIZATION_WRITE scope with EDIT_DETAILS permission. 
PATCH /v3/organization/{id}/icon?ext=png

​
Path Parameters

​
id
string
required
The organization ID or slug

​
Query Parameters

​
ext
string
required
Image file extension (png, jpg, jpeg, gif, webp, svg)

​
Request Body

Binary image data (max 256 KiB)

​
Behavior

  • Deletes the old icon if one exists
  • Uploads and optimizes the new icon
  • Extracts a primary color from the image
  • Updates the organization’s icon_url, raw_icon_url, and color fields

​
Example Request

curl -X PATCH 'https://api.modrinth.com/v3/organization/my-org/icon?ext=png' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary '@icon.png'

​
Delete Organization Icon

Remove the organization’s icon. Requires authentication and ORGANIZATION_WRITE scope with EDIT_DETAILS permission. 
DELETE /v3/organization/{id}/icon

​
Path Parameters

​
id
string
required
The organization ID or slug

​
Example Request

curl -X DELETE https://api.modrinth.com/v3/organization/my-org/icon \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get Organization Members

Get all members of an organization’s team. 
GET /v3/organization/{id}/members

​
Path Parameters

​
id
string
required
The organization ID or slug

​
Response

Returns an array of team member objects.

​
Example Request

curl https://api.modrinth.com/v3/organization/my-org/members

​
Example Response

[
  {
    "user": {
      "id": "9dU94F4T",
      "username": "jellysquid",
      "avatar_url": "https://cdn.modrinth.com/avatars/9dU94F4T.png"
    },
    "role": "Owner",
    "permissions": 255,
    "organization_permissions": 255,
    "accepted": true,
    "payouts_split": 10000,
    "ordering": 0
  }
]

​
Organization Permissions

Organization members have specific permissions that control what they can do:
  • EDIT_DETAILS - Edit organization name, slug, description, and icon
  • MANAGE_INVITES - Invite new members to the organization
  • REMOVE_MEMBER - Remove members from the organization
  • EDIT_MEMBER - Edit member roles and permissions
  • ADD_PROJECT - Add projects to the organization
  • REMOVE_PROJECT - Remove projects from the organization
  • DELETE_ORGANIZATION - Delete the entire organization
These are separate from project permissions and are stored in the organization_permissions field of team members.

​
Common Use Cases

Creating an Organization
  1. Call POST /v3/organization with name, slug, and description
  2. You become the organization owner automatically
  3. Upload an icon with PATCH /v3/organization/{id}/icon
  4. Invite team members using the Teams API
Adding Projects to an Organization
  1. You must be the owner of the project
  2. You must have ADD_PROJECT permission in the organization
  3. Call POST /v3/organization/{id}/projects with the project ID
  4. All organization members now have access to the project
Managing Organization Teams
  • Use the standard Teams API endpoints with the organization’s team_id
  • Set organization_permissions when adding members
  • Organization owners have full permissions by default
Transferring Projects
  1. To move between organizations: Remove from old org, add to new org
  2. To make independent: Remove from org and specify new owner
  3. Original team members remain on the project team