Top-level API endpoints
Endpoints for authenticating to the server or checking authentication status
Endpoints that are not yet considered stable. Their request parameters and response formats are subject to change without warning (even more so than the rest of the API), and they may not be available on all servers.
Currently, all endpoints in this category are used to query for current/recent PVP activity.
See the Endpoints: /warpath category for similar endpoints
Endpoints used to read or modify game state
Endpoints for reading or modifying the state of the in-game market
Endpoints for querying control/power leaderboards
See the Endpoints: /scoreboard category for seasonal world competition leaderboards
Endpoints for creating new user accounts
Endpoints for querying scoreboard results
This appears to only be relevant to seasonal world competitions/events.
See also:
Endpoints: /seasons category: seasonal world metadata endpointsEndpoints: /leaderboard category: for non-seasonal leaderboard endpointsEndpoints for seasonal world events.
See the Endpoints: /scoreboard category for seasonal world scoreboard endpoints
Endpoints that provide information about other servers
Endpoints for reading or modifying state about the authenticated user, or for looking up information on other users
Endpoints for downloading or uploading code
Endpoints for managing decorations
Endpoints for reading from or writing to Memory.
Endpoints for reading from or writing to RawMemory.segments.
Endpoints for reading or managing in-game messages
Endpoints for querying current/recent PVP activity by room.
These may not be implemented on all servers. Most notably, they are not available on official servers, but the third-party service Voight-Kampff provides these and more for official servers and popular community servers.
See the Endpoints: /experimental category for similar endpoints
Describes the server mod used for authentication on unofficial servers.
For official servers, the name of the mod is always 'official'.
This endpoint does not require authentication.
Endpoint: GET /api/authmod
Fetch a chunk of history data for a single room.
Official Endpoint: GET /room-history/${shard}/${room}/${tick}.json
Unofficial Endpoint: GET /room-history
Name of the room for which to fetch history
Tick for which history should be fetched
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
ScreepsApiError if history is unsupported or the requested chunk is missing
version returns the history chunk size to expect
Fetch basic information about a server, including versioning info, available shards, available features, and more.
This endpoint does not require authentication.
Endpoint: GET /api/version
Fetch information about the authenticated user.
Endpoint: GET /api/auth/me
Query the status/permissions of an API token.
Endpoint: GET /api/auth/query-token
The API token for which permissions should be queried
ScreepsApiError if the token is invalid / not recognized.
ScreepsHttpClient.token for the API token currently in use by this client
Authenticate to the server using email/password credentials.
This authentication method has not worked on official servers since 2018, but it is still used for unofficial servers.
Endpoint: POST /api/auth/signin
The email address used for registration
The password used for registration
Authenticate via Steam SSO.
Steam and Github SSO are the only permitted authentication methods on official servers.
Endpoint: POST /api/auth/steam-ticket
Do you know what this does? If so, please submit a PR!
Do you know what this does? If so, please submit a PR!
Find all active nuclear launches.
Endpoint: GET /api/experimental/nukes
Find rooms where attack actions have recently occurred (including combat actions against NPCs).
Endpoint: GET /api/experimental/pvp
Minimum time (in ticks?) since last combat action
Trigger an action on one or more objects.
This endpoint is used for a variety of actions, depending on the name and intent parameters.
Endpoint: POST /api/game/add-object-intent
the ID of the object that should perform the intent
the name of the room the object is in
name of the intent (ex: 'move')
Optionalintent: stringJSON string describing the target(s) of the intent (for actions like 'heal' or 'build')
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
destroy structure: _id = "room", name = "destroyStructure", intent = [ {id: <structure id>, roomName, <room name>, user: <user id>} ]
can destroy multiple structures at once
Change the color of an existing flag.
Endpoint: POST /api/game/change-flag-color
The color of the left side of the flag
The color of the right side of the flag
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Check whether or not a flag name is in use.
Checks all existing flags owned by the authenticated user on the specified shard for one with the specified name.
Endpoint: POST /api/game/check-unique-flag-name
The name to check
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server. Also throws an error if the flag name is already in use.
Check whether or not a name for a room object is in use by any other room object of the same type on the specified shard.
Endpoint: POST /api/game/check-unique-object-name
The type of object being named. 'spawn' is the only known valid argument for this param.
'flag' and 'creep' will cause an error.
The name to check
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server.
ScreepsApiError if the object name is already in use.
Create a construction site for a new structure.
Unlike the runtime API equivalent of this endpoint, room visibility is not required here.
Endpoint: POST /api/game/create-construction
Name of the room in which to place the site
X-coordinate of the site's room position
Y-coordinate of the site's room position
The type of structure to build (ex: 'road', 'powerSpawn')
Optionalname: stringAn optional name to assign to the placed structure.
This should be undefined unless structureType is 'spawn'.
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Create a new flag or move an existing one with the specified name.
Unlike the runtime API equivalent of this endpoint, room visibility is not required here.
Endpoint: POST /api/game/create-flag
Name of the room in which the flag should be placed
X-coordinate of the flag's room position
Y-coordinate of the flag's room position
The name of the flag. If the name is already in use, the current flag with this name will be moved to the specified position.
The color of the left side of the flag
The color of the right side of the flag
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
A generic MongoDB upsert response:
result.upserted[0]._id is the game id of the created flagError if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Create an invader creep in a room claimed by the authenticated user.
Create a single invader to test the defenses of one of your rooms. This can be called multiple times in succession to simulate a raid group.
Invaders created by this endpoint will not drop any resources on death. They can be removed by gameRemoveInvader
This operation is only permitted on exit positions of rooms claimed by the authenticated user.
Endpoint: POST /api/game/create-invader
Name of the room in which to spawn
X-coordinate of the invader's room position
Y-coordinate of the invader's room position
The body size of the invader. In real invasions, the small size spawns in unclaimed and low-RCL rooms, while the large size spawns in high-RCL rooms.
The role of the invader, which will determine its body part types, boost types, and behavior.
If true, the invader will be spawned with boosted parts.
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Generate a name for a new flag.
The generated name will be unique across all other flags owned by the authenticated user on the specified shard.
Endpoint: POST /api/game/gen-unique-flag-name
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Generate a name for a new room object.
The generated name will be unique across all other objects of that type owned by the authenticated user on the specified shard.
Endpoint: POST /api/game/gen-unique-object-name
The type of object for which to generate the name (ex: "flag" or "spawn")
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch statistics for one or more rooms along with basic information like owner and RCL.
Endpoint: POST /api/game/map-stats
An array of one or more room names.
The type of stat to fetch. See Http.MapStat.
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Place the authenticated user's first spawn structure.
This operation is only permitted when the user's
world status
is equal to 'empty'.
Endpoint: POST /api/game/place-spawn
Name of the room in which the spawn should be placed
X-coordinate of the spawn's room position
Y-coordinate of the spawn's room position
Optionalname: stringAn optional name to assign to the placed spawn
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Delete a flag by name.
Endpoint: POST /api/game/remove-flag
The name of the room in which the flag is placed
The name of the flag to remove
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Remove an invader creep created by gameCreateInvader.
This operation is only permitted on invaders created by the authenticated user via the gameCreateInvader endpoint.
Endpoint: POST /api/game/remove-invader
The ID of the invader creep to remove
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch all active decorations for a specific room.
Endpoint: GET /api/game/room-decorations
The name of the room
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch all room objects present in a specific room.
Endpoint: GET /api/game/room-objects
The name of the room
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Get the authenticated user's stats for a room broken down by time.
Endpoint: GET /api/game/room-overview
The name of the room
Size of each time slot in minutes; only specific values are allowed:
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Look up the status of a room.
Endpoint: GET /api/game/room-status
The name of the room
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch terrain data for a specific room and return it in an "encoded" format.
Endpoint: GET /api/game/room-terrain
The name of the room
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
gameRoomTerrainUnencoded for an alternative response format
Fetch terrain data for a specific room and return it in an "unencoded" format.
Warning: In rare circumstances (unofficial servers that are using maps generated via the map.generateRoom CLI command), this endpoint will return encoded terrain data instead of unencoded data.
Endpoint: GET /api/game/room-terrain
The name of the room
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
gameRoomTerrain for an alternative response format
Enable or disable attack notifications on a single room object.
Endpoint: POST /api/game/set-notify-when-attacked
ID of the room object
true to enable notifications, or false to disable notifications
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch the current game time
Endpoint: GET /api/game/time
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch the width and height (in rooms) of the specified shard's world map.
Endpoint: GET /api/game/world-size
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch all unexpired market orders created by the authenticated user.
Endpoint: GET /api/game/market/my-orders
Fetch all active market orders for a given resource type.
Endpoint: GET /api/game/market/orders
Any resource type
Optionalshard: stringIf resourceType is an IntershardResource, this must be set to undefined.
ScreepsClientConfig.defaultShard is ignored here for compatibility with intershard resources.
Get an overview of market data for a shard.
Intershard market data is always included, if available.
Endpoint: GET /api/game/market/orders-index
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch market history data for a given resource type.
Endpoint: GET /api/game/market/stats
Any resource type
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch high-level data about all available shards on this server.
This endpoint does not require authentication.
Endpoint: GET /api/game/shards/info
Fetch the leaderboard rankings for a specific user.
This endpoint does not require authentication.
Endpoint: GET /api/leaderboard/find
The name of the user
'world' (control points) or 'power' (power processed)
Optionalseason: stringAn optional date in the format YYYY-MM. If undefined, the user's ranks for all seasons is returned.
Fetch the leaderboard rankings for a specific user.
This endpoint does not require authentication.
Endpoint: GET /api/leaderboard/list
The number of user results to include per response
'world' (control points) or 'power' (power processed)
The index (starting at zero) of the first leaderboard position that should be included in the response
Optionalseason: stringA date in the format YYYY-MM, NOT a seasonal world name/number.
Defaults to the current season.
Fetch a list of all seasons for which leaderboard rankings exist. Note that the "seasons" mentioned here are distinct from the official seasonal world competitions.
This endpoint does not require authentication.
Endpoint: GET /api/leaderboard/seasons
Checks the availability of an email address.
This endpoint does not require authentication.
Endpoint: GET /api/register/check-email
The email address to check
If the exmail is available, returns Http.ScreepsResponse.
If the email is taken, returns Http.ScreepsErrorResponse
({ error: 'exists' }).
Checks the availability of a username.
This endpoint does not require authentication.
Endpoint: GET /api/register/check-username
The username to check
If the username is available, returns Http.ScreepsResponse.
If the username is taken, returns Http.ScreepsErrorResponse
({ error: 'exists' }).
Endpoint: POST /api/register/set-username
The username to associated with this account
Please consider submitting a PR to document the success response.
If used for an account that is already set up, returns
Http.ScreepsErrorResponse ({ error: 'username already set' }).
Create a new user account.
Endpoint: POST /api/register/submit
The username to use for this new account
The email address to associate with this new account
The password to use for this new account. It is unclear whether or not this is accepted or even allowed on official servers.
Optionalmodules: UserCodeModulesInitial bot code to deploy for this user
Query scoreboard results. This appears to only be relevant to seasonal world competitions/events.
Endpoint: GET /api/scoreboard/list
The index (starting at zero) of the first leaderboard position that should be included in the response
The number of users to return per request. The maximum valid value is 20.
Fetch metadata for the current season. Only works on official servers when a seasonal world competition is active or about to start.
Endpoint: GET /api/seasons/current
Metadata on the current season, or null if a seasonal world competition is not active or about to start
ScreepsApiError HTTP 404 if called on an unofficial server
Fetch a curated list of community servers.
This endpoint does not require authentication.
Endpoint: POST /api/servers/list
ScreepsApiError HTTP 404 if used on an unofficial server
Unlock CPU on PTR for one week.
Endpoint: POST /api/user/activate-ptr
an Http.ScreepsResponse on PTR, or an Http.ScreepsErrorResponse
({ error: 'not ptr' }) on official servers that are not PTR.
ScreepsApiError HTTP 404 on unofficial servers
Update the authenticated user's badge.
Endpoint: POST /api/user/badge
Fetch a list of all code branches the authenticated user has on the server.
Endpoint: GET /api/user/branches
Create a copy of a code branch.
Endpoint: POST /api/user/clone-branch
The name of the code branch to clone
The name of the new code branch
Do you know what this does? If so, please submit a PR!
userBranches to list available branches
Evaluate a JavaScript expression in the context of the authenticated user's bot's runtime environment.
This expression is evaluated after the user's loop function runs. CPU costs and limits apply as they would to code in the loop function.
Endpoint: POST /api/user/console
The JavaScript expression to evaluate.
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Update the authenticated user's shard CPU limits.
Endpoint: POST /api/user/cpu-shards
The user's new shard CPU limits. See CpuShardLimits
Delete a code branch.
Endpoint: POST /api/user/delete-branch
The name of the code branch to delete
Update the authenticated user's email address.
Endpoint: POST /api/user/email
The user's new email address
Find a user by name.
Endpoint: GET /api/user/find
The complete username of the user
userFindById to find a user by ID instead of username
Find a user by ID.
Endpoint: GET /api/user/find
The ID of the user
userFind to find a user by username instead of ID
Fetch a list of the authenticated user's most recent market transactions.
Endpoint: GET /api/user/money-history
Used for pagination
Fetch the authenticated user's username.
Endpoint: GET /api/user/name
Update the authenticated user's notification preferences.
Endpoint: POST /api/user/notify-prefs
Get an overview of the authenticated user's stats broken down by room and time.
Endpoint: GET /api/user/overview
Size of each time slot in minutes; only specific values are allowed:
The stat to view for this user
Abandon all of the authenticated user's rooms to allow them to pick a new spawn room.
Endpoint: POST /api/user/respawn
Look up the name of the room in which this player may not respawn.
Endpoint: GET /api/user/respawn-prohibited-rooms
Find all rooms claimed by the specified user.
Endpoint: GET /api/user/rooms
The ID of the user
Update the code branch that will be used by the server or the simulator.
Endpoint: POST /api/user/set-active-branch
The name of the code branch to activate
The environment for which this code branch should be activated:
userBranches to list available branches
Look up stats for a user.
Endpoint: GET /api/user/stats
ID of the user
The time interval in minutes (divided by 8); only specific values are allowed:
userOverview for more detailed stats for the authenticated user
Mark tutorial as completed for the authenticated user.
Endpoint: POST /api/user/tutorial-done
Get the name of a room that should be centered on the authenticated user's map when opening the map view on the client with no coordinates.
Endpoint: GET /api/user/world-start-room
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Get the authenticated user's status on the server.
Endpoint: GET /api/user/world-status
Pull the authenticated user's code and WASM binaries for a specific branch.
Endpoint: GET /api/user/code
the name of the branch from which to pull code
Push code and WASM binaries to a branch for the authenticated user.
Endpoint: POST /api/user/code
the code/binaries and target branch
POST /api/user/code response
The name of the branch
ScreepsHttpClient.userBranches to list available branches
JavaScript code and WASM binaries keyed by module name
Apply / activate a decoration to a creep/object/room.
Endpoint: POST /api/user/decorations/activate
the ID of the decoration to activate
values to assign to configurable properties
Destroy one or more owned decorations to refund a fraction of their pixelization cost.
Endpoint: POST /api/user/decorations/convert
The IDs of one or more owned decorations
Remove / deactivate one or more active decorations.
Endpoint: POST /api/user/decorations/deactivate
The IDs of one or more active decorations
Fetch all of the authenticated user's decorations.
Endpoint: GET /api/user/decorations/inventory
Spend pixels to create one or more decorations.
Endpoint: POST /api/user/decorations/pixelize
The number of decorations to generate.
The theme from which to generate decorations. Note that specifying a theme increases the pixelization cost. Set to an empty string to create decorations from any theme.
Fetch all themes under which the user's decorations can be grouped.
Endpoint: GET /api/user/decorations/themes
Retrieves part or all of the authenticated user's Memory.
Endpoint: GET /api/user/memory
Optionalpath: stringThe portion of the Memory JSON object to retrieve (ex: 'flags.Flag1'). If undefined/empty, returns the entire Memory object.
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Updates part or all of the authenticated user's Memory.
Endpoint: POST /api/user/memory
The portion of the Memory JSON object to write (ex: 'flags.Flag1'). WARNING: If undefined/empty, overwrites the entire Memory object.
The value to write to the specified Memory path. This will completely replace the previous value.
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch the contents of one or more RawMemory.segments.
Endpoint: GET /api/user/memory-segment
One or more segment IDs to read. Multiple IDs can be specified in a single string by separating the IDs with commas.
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Update the contents of a single RawMemory.segments.
Endpoint: POST /api/user/memory-segment
A number from 0-99
The data to write to the segment. Non-string values will be serialized on the server side.
Optionalshard: stringThe name of the shard to use (ignored by unofficial servers). Defaults to ScreepsClientConfig.defaultShard if undefined.
Error if shard and ScreepsClientConfig.defaultShard are undefined while using an official server
Fetch the last message from every thread in the authenticated user's inbox.
Endpoint: GET /api/user/messages/index
Search for messages by user ID.
Endpoint: GET /api/user/messages/list
The long _id of the user, not the username
Mark the authenticated user's copy of a message as read.
Endpoint: POST /api/user/messages/mark-read
The ID of the message to mark as read
Send a message on behalf of the authenticated user.
Endpoint: POST /api/user/messages/send
The long _id of the user, not the username
The text of the message to send
Fetch the authenticated user's number of unread messages.
Endpoint: GET /api/user/messages/unread-count
Find active/recent battles by room and classified by conflict intensity.
This endpoint is unavailable on official servers, but the same data is available via Voight-Kampff.
Endpoint: GET /api/warpath/battles
Minimum time (in ticks?) since last observed PVP activity
Warpath Conflict Classifications for the criteria used to assign conflict levels
ReadonlyrateReadonlysocketStatic ReadonlyAUTHFired immediately before authentication status changes.
Payload: boolean Whether or not the client is now authenticated
Static ReadonlyRATE_Fired when a rate limit is exceeded
Payload: RateLimitEvent The latest rate limit state
Static ReadonlyRESPONSEFired when a response is received from the HTTP API.
Payload: AxiosResponse The HTTP response
Static ReadonlyRESPONSE_Fired when a response is received from the HTTP API.
Payload: ScreepsHttpResponse The HTTP response, including params of the associated request
Static ReadonlyTOKENFired immediately before ScreepsHttpClient.token is updated.
Payload: string The new API token
True if this client is configured for the official world, PTR, or seasonal world servers
True if this client is configured for the public test realm (PTR) server
True if this client is configured for the seasonal world server
Generate an URL that can be opened in a browser to reset rate limits for all endpoints.
The generated URL is specific to the API token currently in use.
Error if no API token is available.
The Screeps World server to which this client is currently configured to use.
Use setServer to switch servers.
The API token that this client is currently using for authentication.
Optional[captureThe Symbol.for('nodejs.rejection') method is called in case a
promise rejection happens when emitting an event and
captureRejections is enabled on the emitter.
It is possible to use events.captureRejectionSymbol in
place of Symbol.for('nodejs.rejection').
import { EventEmitter, captureRejectionSymbol } from 'node:events';
class MyClass extends EventEmitter {
constructor() {
super({ captureRejections: true });
}
[captureRejectionSymbol](err, event, ...args) {
console.log('rejection happened for', event, 'with', err, ...args);
this.destroy(err);
}
destroy(err) {
// Tear the resource down here.
}
}
Authenticate to the server using the email and password from the provided ScreepsServerConfig.
Typically, this should not be called directly; it will be triggered automatically when a request is made to an endpoint that requires authentication.
Optionalcause: unknownif provided, will be attached to the error thrown when authentication credentials are missing
ScreepsApiError if authentication fails
Enable or disable debug logging via the Debug package.
Optionalopts: DebugOptionsIf undefined, disables debug logs for all namespaces. Otherwise, enables the specified namespaces and disables all others.
Synchronously calls each of the listeners registered for the event named
eventName, in the order they were registered, passing the supplied arguments
to each.
Returns true if the event had listeners, false otherwise.
import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();
// First listener
myEmitter.on('event', function firstListener() {
console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
const parameters = args.join(', ');
console.log(`event with parameters ${parameters} in third listener`);
});
console.log(myEmitter.listeners('event'));
myEmitter.emit('event', 1, 2, 3, 4, 5);
// Prints:
// [
// [Function: firstListener],
// [Function: secondListener],
// [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
Returns an array listing the events for which the emitter has registered listeners.
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});
const sym = Symbol('symbol');
myEE.on(sym, () => {});
console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
ProtectedgzReturns the number of listeners listening for the event named eventName.
If listener is provided, it will return how many times the listener is found
in the list of the listeners of the event.
The name of the event being listened for
Optionallistener: (...args: any[]) => voidThe event handler function
Returns a copy of the array of listeners for the event named eventName.
server.on('connection', (stream) => {
console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]
ProtectedmapFetch and memoize information about the authenticated user.
If using an API token with full permissions, Http.AuthMeResponse. Otherwise the result is Http.UserInfo.
Adds the listener function to the end of the listeners array for the
event named eventName. No checks are made to see if the listener has
already been added. Multiple calls passing the same combination of eventName
and listener will result in the listener being added, and called, multiple
times.
server.on('connection', (stream) => {
console.log('someone connected!');
});
Returns a reference to the EventEmitter, so that calls can be chained.
By default, event listeners are invoked in the order they are added. The
emitter.prependListener() method can be used as an alternative to add the
event listener to the beginning of the listeners array.
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a
The name of the event.
The callback function
Adds a one-time listener function for the event named eventName. The
next time eventName is triggered, this listener is removed and then invoked.
server.once('connection', (stream) => {
console.log('Ah, we have our first user!');
});
Returns a reference to the EventEmitter, so that calls can be chained.
By default, event listeners are invoked in the order they are added. The
emitter.prependOnceListener() method can be used as an alternative to add the
event listener to the beginning of the listeners array.
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a
The name of the event.
The callback function
Adds the listener function to the beginning of the listeners array for the
event named eventName. No checks are made to see if the listener has
already been added. Multiple calls passing the same combination of eventName
and listener will result in the listener being added, and called, multiple
times.
server.prependListener('connection', (stream) => {
console.log('someone connected!');
});
Returns a reference to the EventEmitter, so that calls can be chained.
The name of the event.
The callback function
Adds a one-time listener function for the event named eventName to the
beginning of the listeners array. The next time eventName is triggered, this
listener is removed, and then invoked.
server.prependOnceListener('connection', (stream) => {
console.log('Ah, we have our first user!');
});
Returns a reference to the EventEmitter, so that calls can be chained.
The name of the event.
The callback function
Returns a copy of the array of listeners for the event named eventName,
including any wrappers (such as those created by .once()).
import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));
// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];
// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();
// Logs "log once" to the console and removes the listener
logFnWrapper();
emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');
// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');
Removes all listeners, or those of the specified eventName.
It is bad practice to remove listeners added elsewhere in the code,
particularly when the EventEmitter instance was created by some other
component or module (e.g. sockets or file streams).
Returns a reference to the EventEmitter, so that calls can be chained.
OptionaleventName: string | symbolRemoves the specified listener from the listener array for the event named
eventName.
const callback = (stream) => {
console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);
removeListener() will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified eventName, then removeListener() must be
called multiple times to remove each instance.
Once an event is emitted, all listeners attached to it at the
time of emitting are called in order. This implies that any
removeListener() or removeAllListeners() calls after emitting and
before the last listener finishes execution will not remove them from
emit() in progress. Subsequent events behave as expected.
import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
const callbackA = () => {
console.log('A');
myEmitter.removeListener('event', callbackB);
};
const callbackB = () => {
console.log('B');
};
myEmitter.on('event', callbackA);
myEmitter.on('event', callbackB);
// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
// A
// B
// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
// A
Because listeners are managed using an internal array, calling this will
change the position indexes of any listener registered after the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the emitter.listeners() method will need to be recreated.
When a single function has been added as a handler multiple times for a single
event (as in the example below), removeListener() will remove the most
recently added instance. In the example the once('ping')
listener is removed:
import { EventEmitter } from 'node:events';
const ee = new EventEmitter();
function pong() {
console.log('pong');
}
ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);
ee.emit('ping');
ee.emit('ping');
Returns a reference to the EventEmitter, so that calls can be chained.
Send an API request to the server.
Unless you are retrying a request using a ScreepsHttpRequest instance, this should not be called directly. Instead, use the appropriate endpoint method to apply the correct request parameter and response body types.
If an endpoint you use does not have an associated method, please consider submitting a PR to implement it.
The HTTP method to use
The URL path of the endpoint. This will be appeneded to ScreepsServerConfig.url.
Optionalparams: unknownThe request parameters
The number of retries already attempted due to HTTP 429 errors. This argument should not be provided by consumers.
The parsed response body
By default EventEmitters will print a warning if more than 10 listeners are
added for a particular event. This is a useful default that helps finding
memory leaks. The emitter.setMaxListeners() method allows the limit to be
modified for this specific EventEmitter instance. The value can be set to
Infinity (or 0) to indicate an unlimited number of listeners.
Returns a reference to the EventEmitter, so that calls can be chained.
Switch to a different server.
If the new server is using email/password auth, the client will attempt to authenticate automatically.
The config for the new server the client should use. This will be normalized by ScreepsConfigManager before being stored in server.
ScreepsApiError if authentication fails
Fetch and memoize permissions and other information about the API token currently being used by this client.
StaticfromSearch for a config/credential file and initializes the client from the first file found.
Authentication will occur automatically if email/password credentials are provided in lieu of an API token.
Alternatively, the client can be initialized by passing a configuration object directly to the constructor.
The property name of the server object to use from the config file
Optionalopts: LoadConfigOptionsA configured and authenticated ScreepsHttpClient instance
Error if the selected config file is invalid or if no config files are found
Provides access to the Screeps HTTP Http.
Please note that the Screeps HTTP API is not technically a public API; it merely exists to power the game's official Steam and web clients. While the game's developers welcome its use, the implicit caveat is that the API is subject to change without warning.
All endpoint methods are asynchronous.
Some of endpoints behave differently on official servers (i.e. any server with the screeps.com hostname) than they do on unofficial/private servers. Any known discrepancies are documented on the relevant endpoint.
Almost all endpoints require the user to be authenticated to use. Any known exceptions to this rule are documented.
All endpoint methods are backed by req, which provides shared error handling logic, etc. If an endpoint does not have a corresponding method defined here, req may be called to access that endpoint directly (albeit without request parameter or response type annotations). Please consider submitting a PR to add functions for any missing endpoints!
Instances should typically be initialized via ScreepsHttpClient.fromConfig, but the constructor can also be called directly if you prefer to handle loading the credentials and configuration options yourself.
See
ScreepsSocketClient for the WebSocket API client (accessible via ScreepsHttpClient.socket)
Example