Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


This is an unofficial client for the Screeps Unoffical API.

Since the API is unofficial it could in theory change at any time. In practice though breaking changes are rare.


Simply install the Python screepsapi library using pip.



The recommended way to authenticate to the official servers is providing an Authorization Token in the token parameter.

import screepsapi
TOKEN = "3bdd1da7-3002-4aaa-be91-330562f54093"
api = screepsapi.API(token=TOKEN)

An optional prefix parameter can be included with values such as "/ptr" for the public test realm or "/season" for seasonal server.

It is also possible to access private servers with the host and secure parameters.

import screepsapi
USER = "MyUsername"
PASSWORD = "TimeTravelingSecretAgentForHire"
HOST = ""
api = screepsapi.API(USER, PASSWORD, host=HOST, secure=True)

Note that by default private servers do not use SSL and all traffic is unencrypted.


Developers are encouraged to align with SS3: Unified Credentials File v1.0 to standardize Screeps credentials storage with other third party tools.


The API class is a simple REST-based API. Each method corresponds to a different Screeps API endpoint.

The best way to discover functionality is to read through the screepsapi library or

Console Example

import screepsapi
TOKEN = "3bdd1da7-3002-4aaa-be91-330562f54093"
api = screepsapi.API(token=TOKEN)

# Run "Game.time" on shard1 via the console
api.console("Game.time", shard="shard1")

User Information Example

import screepsapi
TOKEN = "3bdd1da7-3002-4aaa-be91-330562f54093"
api = screepsapi.API(token=TOKEN)

# Find the GCL for "tedivm"
user = api.user_find("tedivm")
print user["user"]["gcl"]


Screeps provides a sizable amount of data over a websocket. This includes console data and room details.

The best way to utilize the socket is to extend screepsapi.Socket and override the various abstract functions.