BinderHub API Documentation#


There’s one API endpoint, which is:


Even though it says build it actually performs launch.

  • provider_prefix identifies the provider.

  • spec defines the source of the computing environment to be built and served using the given provider.


The provider_prefix can be any of the supported repository providers in BinderHub, see the Repository Providers section for supported inputs.

To use this endpoint, construct an appropriate URL and send a request.

You’ll get back an Event Stream. It’s pretty much just a long-lived HTTP connection with a well known JSON based data protocol. It’s one-way communication only (server to client) and is straightforward to implement across multiple languages.

When the request is received, the following happens:

  1. Check if this image exists in our cached image registry. If so, launch it.

  2. If it doesn’t exist in the image registry, we check if a build is currently running. If it is, we attach to it and start streaming logs from it to the user.

  3. If there is no build in progress, we start a build and start streaming logs from it to the user.

  4. If the build succeeds, we contact the JupyterHub API and start launching the server.


This section catalogs the different events you might receive.


Emitted whenever a build or launch fails. You must close your EventStream when you receive this event.

{'phase': 'failed', 'message': 'Reason for failure'}


Emitted after the image has been built, before launching begins. This is emitted in the start if the image has been found in the cache registry, or after build completes successfully if we had to do a build.

{'phase': 'built', 'message': 'Human readable message', 'imageName': 'Full name of the image that is in the cached docker registry'}

Note that clients shouldn’t rely on the imageName field for anything specific. It should be considered an internal implementation detail.


Emitted when we started a build pod and are waiting for it to start.

{'phase': 'waiting', 'message': 'Human readable message'}


Emitted during the actual building process. Direct stream of logs from the build pod from repo2docker, in the same form as logs from a normal docker build.

{'phase': 'building', 'message': 'Log message'}


Emitted when fetching the repository to be built from its source (GitHub, GitLab, wherever).

{'phase': 'fetching', 'message': 'log messages from fetching process'}


Emitted when the image is being pushed to the cache registry. This provides structured status info that could be in a progressbar. It’s structured similar to the output of docker push.

{'phase': 'pushing', 'message': 'Human readable message', 'progress': {'layer1':  {'current': <bytes-pushed>, 'total': <full-bytes>}, 'layer2': {'current': <bytes-pushed>, 'total': <full-bytes>}, 'layer3': "Pushed", 'layer4': 'Layer already exists'}}


When the repo has been built, and we’re in the process of waiting for the hub to launch. This could end up succeeding and emitting a ‘ready’ event or failing and emitting a ‘failed’ event.

{'phase': 'launching', 'message': 'user friendly message'}


When your notebook is ready! You get a endpoint URL and a token used to access it. You can access the notebook / API by using the token in one of the ways the notebook accepts security tokens.

{"phase": "ready", "message": "Human readable message", "url": "full-url-of-notebook-server", "token": "notebook-server-token"}


In EventSource, all lines beginning with : are considered comments. We send a :heartbeat every 30s to make sure that we can pass through proxies without our request being killed.