The SMR API is designed to be simple to use.
Calls are made using either application/x-www-form-urlencoded or multipart/form-data
The method can be freely chosen as long as no file is uploaded.
In that case, the latter is required
The entire API is designed to resist issues like intermittent connections. It's ok to issue the exact same call again if the connection was interrupted. API calls are atomic in nature; No single operation requires multiple API calls.
If you prefer reading code over documentation you can find a working reference implementation here. It implements all API functions and also shows how to properly get a users token without ever passing the username or password through your application.
The API uses browser compatible types on purpose.
The content-type for requests are the two that are used for regular forms.
The response is given in XML,
which the XMLHttpRequest object automatically parses into a tree structure for you
so that you can use DOM methods like querySelector on.
We set the Access-Control-Allow-Origin header too,
to allow you to use this in your website purely client side in JavaScript.
A very crude API client to get you started can be found in API.js
Some API calls might send caching headers. We recommend you adhere to them to preserve bandwidth of the user. This is done automatically if you use our API from a web browser.
All API requests need an API key.
You can find this key in your account page.
The special "nullguid" 00000000-0000-0000-0000-000000000000 can be used to make anonymous requests.
To obtain the API key from a user, head over to the remote authentication page.
Fields depend on the mode.
The only required field that is identical for all modes is
key=00000000-0000-0000-0000-000000000000.
The mode parameter is appended to the URL.
Example: Using the test function is done using /satisfactory/maps/api/test as URL.
The Answer is an XML document.
The root element is always <api>.
Following child nodes are always present:
true or false.
If false, the msg node contains failure reason.
If true, the data node contains the response.
<data> node.
The list below contains a list of all supported entry types.
Type 0 is special.
It can't be used when submitting maps to the API and merely serves as a fallback in case a type is deleted.
This list is also returned in the "info" mode.
| Id | Type Name | Description |
|---|---|---|
| 0 | unknown | Unknown category. Can't be selected by the user. If one of your map has this category, update its category list please. |
| 1 | creative | This map was (partially) built using creative mode. This is no indication if creative mode is still enabled or not. |
| 2 | edited | This map was edited in a save file editor. This only concerns significant edits like creating items, restoring things on the map that were taken or removing things. |
| 3 | nature | This map integrates nature rather than building everything on foundations or in the sky |
| 4 | foundations | Most things are built on foundations |
| 5 | global grid | The majority of foundations on this map are aligned on a global grid |
| 6 | complete research | Research has been completed |
| 7 | complete alts | All alternate recipes have been unlocked |
| 8 | all products | All products are made on this map |
| 9 | outpost | This map utilizes outposts and ships processed materials around rather than raw materials |
| 10 | central factory | This map makes everything in a central factory |
| 11 | belts only | Belts only, no vehicles for material transport |
| 12 | clean energy | This factory uses clean energy only (biomass + geothermal) |
| 13 | nuclear energy | This factory features nuclear energy |
| 14 | trains | This factory relies on trains |
| 15 | cars | This factory relies on trucks and tractors |
| 16 | full minimap | The minimap is fully explored |
| 17 | perfect ratios | All ratios in this factory are perfect or as close to perfect as possible |
| 18 | sky base | Most things are built high above the ground |
| 19 | untouched nature | No leaves, flowers, wood, berries, nuts or mushrooms were taken, or they were restored using an editor |
| 20 | untouched artifacts | No artifacts were taken, or they were restored using an editor |
| 21 | untouched slugs | No slugs were taken, or they were restored using an editor |
| 22 | untouched animals | No aminals were slain, or they were restored using an editor |
| 23 | fun | These are maps purely made for the entertainment of the player. For example large arrays of jump pads and map encompassing train tracks |
| 24 | art | Map that is art, either via minimap or ingame pixel art for example |
| 25 | landmarks | Map that contains large buildings created for aesthetic purposes, for example real looking skyscrapers or big suspension bridges |
| 26 | warehouse | Map features a warehouse style location where every item is obtainable from containers with the possible exclusion of raw and nuclear materials as well as player equipment |
| 27 | challenge | This map solves an arbitrary challenge or provides one for the player |
| 28 | spaghetti | Not a lot of care has been taken when placing belts, going for a more direct route |
| 29 | perfect alignment | Belts are neatly aligned to 90°, even if it means much longer belts |
| 30 | OCD Complete | Everything is perfect. Belt layouts, machine placements, ratios. Just everything |
Some categories can't be used in combination with some other categories.
The list below contains the conflicts.
Note: The list is bidirectional. If category n conflicts with m,
the entry for m will also list n as conflict.
A category that lists itself as conflict is essentially disabled.
The list is also given in the "info" API command.
Category 0 is stipped from the list below to shorten it, but it is present in the API command.
| Id | Name | Conflicts |
|---|---|---|
| 3 | nature | 4, 18 |
| 4 | foundations | 3 |
| 9 | outpost | 10 |
| 10 | central factory | 9 |
| 11 | belts only | 14, 15 |
| 12 | clean energy | 13 |
| 13 | nuclear energy | 12 |
| 14 | trains | 11 |
| 15 | cars | 11 |
| 18 | sky base | 3 |
| 28 | spaghetti | 29, 30 |
| 29 | perfect alignment | 28 |
| 30 | OCD Complete | 28 |
Unless otherwise stated, values are given as the text of an Xml Node.
A valid Id is a UUID,
for example 710b672b-41d2-47c7-bfd8-893bc04cfc48.
Do not enclose it in brackets.
Most API calls accept the regular id as well as the hidden id.
You still need to be the owner of the map to modify it, even if the hiden id is supplied.
The structure of a map is as follows:
Numbers are given in "Invariant Culture".
Decimal symbol is always a dot .
No number grouping is performed.
Dates are given in Unix time.
In case you are not familiar with it,
unix time is the number of seconds since 1970-01-01 00:00:00 UTC.
Many programming languages operate on this system.
You need to convert if yours doesn't but it's very simple:
For things that are not entire dates but just a certain amount of time, times are given in seconds. An example would be the total play time stored in a save file.
To submit values that are arrays, specify the key-value pair multiple times with [] as key suffix.
Request body for setting two categories on a map:
key=d86d86d9-69b9-4a63-8d98-8ad28e9099b0&id=62b2516e-e3be-4a4f-ac6a-1ca9a2b126a1&category[]=2&category[]=4
Array keys must always specify the [] suffix even if only used once.
test
This mode tests the API.
It simply returns all fields you sent in the data node.
This mode requires a valid API key even though no personal data is accessed.
This means you can use this to test the validity of the key too.
Both
Any
All sent fields are returned (excluding any uploaded file)
infoReturns the username as well as the list of your maps.
Both
None
detailsReturns a single map entry
Both
The data property of the answer will be a map entry. The "id" and "hidden_id" fields will be absent from the entry.
editEdits an existing map
No
Only the "id" field is required. All other fields are optional and if not specified, will leave that map property unchanged.
.sav is added if missing.Returns the updated map entry. See the "info" help on how this entry looks like
delDeletes a map
No
None. Check the general 'success' field
add
Uploads a map.
Data must be sent as multipart/form-data
No
The map information. See the "info" command on how this structure looks.
newidGenerates a new hidden id for a map.
No
The new hidden id.
listLists public maps
Yes
All fields are optional
These functions can be used as part of the API but work differently. They are regular HTTP GET requests without an API key. For private maps, you have to supply the "hidden id" instead of the regular id.
URL: https://cable.ayra.ch/satisfactory/maps/preview/?map=<map-id>
Delivers a 1000x1000 png image with a preview of the save file.
URL: https://cable.ayra.ch/satisfactory/maps/download/?map=<map-id>
Delivers the save file itself.
Note: For this to work your client must support gzip encoding.