CFWidget

Contact

We now have a Discord! - https://discord.gg/FENdtjAJRF

API

The CurseForge Widget API is available over https at https://api.cfwidget.com. Project details can be retrieved by making a GET request to this endpoint where the path of your request is a current CurseForge project path or a project id.

GET https://api.cfwidget.com/32274
GET https://api.cfwidget.com/minecraft/mc-mods/journeymap

{
   "id": 32274,
   "game": "minecraft",
   "type": "Mods",
   "urls": {...},
   "files": [...]
   "downloads": {...},
   "thumbnail": "...",
   "categories": [...],
   "created_at": "2011-09-19T23:49:04.217Z",
   "description": "...",
   "download": {...}
}

Author details can be retrieved by making a GET request to this endpoint where the path of your request is a current or legacy CurseForge project path.

GET https://api.cfwidget.com/author/9422784
GET https://api.cfwidget.com/author/search/MysticDrew

{
    "projects": [
        {
            "id":32274,
            "name":"JourneyMap"
        },
        {
            "id":225341,
            "name":"JourneyMap Server"
        }
    ],
    "username":"Mysticdrew",
    "id":9422784
}

Images

The CurseForge Widget API is available over https at https://cfwidget.com. An image representing basic data of the project and the latest file is available by passing the project id and any optional parameters.

GET https://cfwidget.com/32274.png

Extra parameters can be provided to alter the image being generated.

dark Generates an image with a black background and white text
transparent Generates an image with the background being transparent instead of black/white
noThumbnail Removes the thumbnail from the resulting image.

Download

Each response includes a download object which is one of the files available on the project. By default the download is the most recent file with a type of release, with a fallback to beta and then alpha if no acceptable file can be found.

Parameters

An optional version parameter can be included when making a request, this will determine which file is used as the download. You may pass a version number, release type, file ID or a combination of version number and release type. For example:

version=alpha Most recent file where release is equal to alpha.
version=1.18.2 Most recent file where version is equal to 1.18.2.
version=1.18.2/beta Most recent file where version is equal to 1.18.2 and release is equal to beta.
version=2288310 File where id is equal to 2288310.

An optional loader parameter can be included when making a request. This will filter the download to only return a file who's versions also contain this loader. For example:

loader=forge Most recent file with the tag of Forge.
loader=fabric Most recent file with the tag of Fabric.
loader=quilt Most recent file with the tag of Quilt.

When a request is made for a version that cannot be satisfied the system will fall back to providing the most recent file as the download, except when the version is a number and release type, in that situation the system will try and satisfy the version number alone before falling back to the most recent file.

Responses

Each request response is a JSON document containing either project data or an error.

200 Project found and data included as the body of the response.
202 Path not found in local database so it has been queued for processing. Retry request in a few seconds.
301 Project is available in database however the path used for the request is not the canonical path. Retry request using the canonical path.
400 Path provided is not a valid CurseForge path or a valid legacy curse.com project path.
404 Path is valid but CurseForge responded that no project exists. This may be because no project has ever lived at this path, or a project does but is hidden from public view.
500 An unknown error occurred processing your request.

Project Data

Data is served from a local database which is populated by extracting data from the CurseForge 3rd Party API. Project data is only updated when a call is made from a consumer to either authors or projects. A consumer can determine data freshness using the last_fetch response value.

Limits

Please be mindful that although there are no rate limits in place, this is a service offered at no cost and as such has limited resources. Aim to make no more than a few concurrent requests per second at peak, and get in touch to discuss options if you need to do anything heavier, as we may be able to find a more suitable solution that protects the service reliability while enabling your use case.

Backwards Compatibility and History

During the many years this service has been operating it has been through many iterations, some required by changes to CurseForge and others required to ensure service reliability. Although the API is always intended to be backwards compatible, there is the potential for breaking changes when data we offer is no longer available through CurseForge. API consumers should be mindful that it is possible that at some point in future data you depend on now may no longer be available and should integrate accordingly.

As of May 11th, 2023, a new endpoint was added that allows rendering a simple widget as an image. URLs using www.cfwidget.com will now return HTML data. If JSON is needed, use api.cfwidget.com instead. The preferred endpoints to use will be cfwidget.com and api.cfwidget.com, where cfwidget.com will return HTML and PNG data, while api.cfwidget.com will return JSON data. This deployment also changed how the backend handles links. This should now avoid issues where paths would generate possibly cycles, and no longer should use redirects, as paths are simply resolved as-is and not redirected elsewhere.

As of June 29th, 2022, the way data is fetched has been changed. Projects and authors will only sync data when requested. This means a project who's not been queried in or has been cached for over an hour will have a longer response time while data is being refreshed. However, this should have no observable impact on the quality of the data. Project resolution is also now instant, where a 202 should not be returned except in rare circumstances.

As of April 1st, 2022, the ability to use the CurseForge path has been re-implemented due to changes by Overwolf. This means paths like /minecraft/mc-mods/journeymap can be resolved and linked to a project.

As of January 1st, 2022, the backend has been rewritten to support scalability and future changes. There was no changes to the API which would cause any forms of breaking, however functionality may feel different. Issues should be reported.

As of December 1st, 2021, 2 new endpoints have been added. Both endpoints return the same JSON structure. The new endpoints allow for getting bare author information. This only includes their id, username, and associated projects that CFWidget is aware of. If a project is missing, then a call to /{projectId} should be made to add the project to the author's list.

/author/{id}
/author/search/{username}

{
  "projects": [
    {
      "id": 32274,
      "name": "JourneyMap"
    },
    {
      "id": 233577,
      "name": "AutoRun"
    },
    {
      "id": 224460,
      "name": "Enhanced Server Moderation"
    },
    {
      "id": 225341,
      "name": "JourneyMap Server"
    }
  ],
  "username": "Mysticdrew",
  "id": 9422784
}

As of April 11th, URLs which contain the Project ID in them (i.e /minecraft/mc-mods/12345) will resolve to the proper ID. This was done to ensure that if we could not determine the path, that there is always a way to do so. Also, urls which use the legacy format (mc-mods/minecraft) will now redirect to the correct path (minecraft/mc-mods).

From 2020, the syncing process has been restored. However, not all data may be present due to the change in APIs used to gather this data. Following fields will no longer have accurate values due to the API changes:

File downloads
License
Donate
Versions will not provide Java version

New fields added:

Summary
File display name

Since 2019, caching has also been implemented on top of the API. Calls to the API will be cached for up to 1 hour.

From 2013 — 2017 this service was available at widget.mcf.li, with API requests made by appending .json to widget URLs. Developers making use of this old format are encouraged to update their integrations to make use of the new request endpoint.

Privacy

All traffic is routed through Cloudflare, which follows the Cloudflare Privacy Policy. No identifiable information is logged or stored on the backend servers.

CurseForge Projects, Anywhere.

Create a Widget