GeezerVison

Toolforge exposes most of its functionality through APIs, currently reachable only from within the Toolforge platform.

You can see a detailed up-to-date description of the methods and details on how to use them in the api-docs.toolforge.org tool.

From time to time some of the endpoints will be deprecated and/or changed in non-backwards compatible ways, we will try to avoid those as much as possible, and follow the protocol described here, it is your responsibility as an API user to adapt your code.

Make sure to subscribe to the cloud-announce mailing list and keep an eye to the Toolforge changelog page.

Currently the API endpoints are only available from within the toolforge environment, this means that you can only access them from the bastion or from within your webservice/jobs.

Access to the Toolforge API from inside the Toolforge project uses an x509 certificate found in a tool's $HOME/.toolskube directory. X509 certificate authentication is only be allowed on the internal API endpoint (https://api.svc.tools.eqiad1.wikimedia.cloud:30003), and not the external one (https://api.svc.toolforge.org).

Deployment tokens will allow you to authenticate on the external endpoint, but only allow you to create deployments from an existing configuration of one specific tool.

See T363983 for work on allowing other authentication methods externally in the future.

import requests
import os

API_URL="https://api.svc.tools.eqiad1.wikimedia.cloud:30003"
MY_TOOL="wm-lol"  # change this to be your tool name
HOME_DIR=os.environ.get("TOOL_DATA_DIR", ".")

my_builds = requests.get(
    f"{API_URL}/builds/v1/tool/{MY_TOOL}/builds",
    cert=(
        f"{HOME_DIR}/.toolskube/client.crt",
        f"{HOME_DIR}/.toolskube/client.key"
    ),
    verify=False  # the cert is currently self-signed, internal to k8s as we use the internal endpoint
).json()

There are some toolforge python packages that are used internally (see https://gitlab.wikimedia.org/repos/cloud/toolforge), but they are not stable yet. We will update these docs when they are stable enough for wider usage.

You may use the openapi spec directly to generate bindings for your language of choice (using https://github.com/OpenAPITools/openapi-generator for example).

• Live API docs
• Portal:Toolforge/Admin#APIs - admin documentation for this feature

Support and administration of the WMCS resources is provided by Wikimedia Foundation staff and Wikimedia movement volunteers. Please reach out with questions and join the conversation: