Organizations API

API endpoints for managing Modrinth organizations and their projects

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

Show properties

user · object

User information including id, username, and avatar_url

role · string

Member’s role/title

permissions · integer

Project permissions bitfield

organization_permissions · integer

Organization-specific permissions bitfield

accepted · boolean

Whether the member has accepted the invitation

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