Skip to content


Repository files navigation


Build Status Moonlight contractors

A light wrapper for the Staffjoy API in Python.

This library does not include permissions management, and it is primarily used across microservices internally. Some of its features include internal-only endpoints.


pip install --upgrade staffjoy

Self-Hosted Use

If you are self-hosting Staffjoy on a custom domain, please pass a url_base to the client. It defaults to". (Trailing slash may matter).

from Staffjoy import Client
c = Client(key=YOUR_API_KEY, url_base="")


Authentication keys are currently tied to an individual user's account. To issue multiple keys, we currently suggest

  • Permanent: Every Staffjoy account includes a permanent API token that can be accessed from My Account while logged in.
  • Time-based (6-hour): To issue an API token that is valid for 6 hours, visit this link while logged in (note: it is JSON-encoded)
  • Time-based (other lengths): Please email

To get your organization ID, look at the URL path when you go to the Manager app while logged in.

Rate Limits

This client sleeps after every request in order to limit requests to 120 per minute. This is done to avoid rate limiting. Staffjoy's API currently rate limits to 300 requests per second across keys and IPs. Thus, by using this library, you should never encounter a rate limit (assuming one executing thread per IP address).


Start with the client, then traverse the tree.

from Staffjoy import Client

c = Client(key=YOUR_API_KEY)

# To get your organization id, look at the URL path for the Manager
# or email
org = c.get_organization(ORG_ID)

# See the org name

# See all locations

# Add an new location
loc = org.create_location(name="Staffjoy HQ", timezone="America/Los_Angeles")

# Modify its name
loc.patch(name="San Francisco")

# See roles
roles = loc.get_roles()

# Create a role and add a worker for scheduling
role = loc.create_role(name="Mathematicians")

# Then clean it all up (recursively deletes node children)