IntroductionCopied!

Our API allows you to perform a wide range of actions in Spaces on the behalf of your institution. This includes creating Spaces, managing events, exporting session analytics or downloading recordings.

Your API key will perform actions in your institution as though those actions were made by the account associated with that key. That is to say, if Institution Admin A creates a Space via API, they will be marked as the owner of that Space unless otherwise specified.

We aim to make our public APIs as exhaustive as possible of all the features in Pencil Spaces. If you’d like to see an API for a feature that isn’t listed in our docs, please do not hesitate to contact us. We’d love to hear your feedback!

Generating API keysCopied!

Authentication is performed by bearer token with your account’s API key. To access your API key, visit Spaces Manager > Settings

Navigate to API Key > Generate and follow the onscreen instructions to generate your key. If you do not see this option in Settings, either your account has not been configured correctly or you do not have sufficient permissions to create an API key. Only Institution Admins can create API keys.

Once your key is generated, for security reasons, it can only be viewed once. After you refresh the page, you’ll only be able to revoke your key.

In case you need to revoke an existing key, you can do so on the same page. Once a key is revoked, you and all other clients logged into your admin account will be logged-out. You will need to log-in to Pencil Spaces again to regenerate your key.

EnvironmentsCopied!

We provide access to two different environments for development. Our staging environment is a restricted environment that is exclusively accessible for developers for limited testing. This environment is not stable and can not be used for production deployments.

Staging Environment

• Available at https://staging.pencilapp.com

• Server URL at: https://staging-apis.pencilapp.com/public/api/

Production Environment

• Available at my.pencilapp.com

• Server URL at: https://apis.pencilapp.com/public/api/

In both cases, you’ll need an Enterprise account to access our API. You can verify you current tier by visiting your billing page. If you’re not on the correct tier, please contact Pencil Spaces support at support@pencilspaces.com and we’d be more than happy to assist.

Best practicesCopied!

We strongly recommend you follow the best practices outlined below to ensure a successful integration:

1. Use an API key associated with a generic admin email. Actions made by an API key are attributed to the account with which the key was generated. We recommend using a generic account on Pencil Spaces (e.g., admin@yourcompany.com ) to make access management easier on your end and to minimise downtime risk.

2. Spaces and users are persistent. There is no need to create and delete Spaces after each session. Users can be reused and re-authenticated, and the same Space can be used over multiple distinct sessions. In this way, students can have a record of all their work in a single link for an entire semester.

3. Limit API request volume to < 5 queries-per-second (QPS) to avoid rate limits and throttling. Several queries, especially those that involve compiling analytics, can take several seconds to complete and have even stricter rate limits. We will automatically reject requests if they hit rate limits with a 429 Too Many Requests HTTP error code.

4. Subscribe to our StatusPage. While outages are rare, they do happen. If you subscribe to our status page, you’ll get live updates as we work to resolve the issue.

5. Contact us via Slack. If you haven’t yet been added to a shared Sla channel with the Pencil Spaces team, please contact your Account Manager. Shared channels mean direct access to our engineers in case anything goes wrong. We’re always here to help!