API Reference

NodePit Runner exposes a REST API that covers every operation available in the UI. Use it to automate workflows, integrate Runner into CI pipelines, or build tooling on top of it.

The full API reference is published as a Swagger UI:

Open API Reference →

Every running Runner instance also ships its own Swagger UI at /api/docs (e.g. http://localhost:8080/api/docs), reflecting the exact version you have deployed. The raw OpenAPI specification is available at /api/docs/json. Both links, ready to copy, are also on the API Access card on the Integrations page 1.31+.

Authentication

The API supports four authentication schemes depending on the use case.

Personal access tokens — the standard way to authenticate external API calls. Tokens are scoped primarily to project-level resources, plus a handful of account-wide reads — see Access Tokens for exactly what's included. They can never modify your profile or account credentials, or create or revoke tokens themselves. Pass the token using the ApiKey scheme:

Authorization: ApiKey <your-token>

See Access Tokens for how to create a token and which scopes are available.

OAuth 1.31+ — the standard way for a third-party application to authenticate on a user's behalf without ever handling their password. Runner runs an OAuth 2.1 authorization server supporting the authorization code flow with PKCE and dynamic client registration; a client discovers the authorization, token, and registration endpoints from:

GET /.well-known/oauth-authorization-server

Every authorization request shows the user a consent screen before a token is issued. The resulting access token is scoped to read or write, same as a personal access token, and is passed the same way:

Authorization: ApiKey <access-token>

Access tokens are short-lived and renew automatically via a refresh token, for as long as the connection keeps being used. See Connected Applications for how users review and revoke a connection, and AI Assistant (MCP Server) for the concrete flow an MCP client uses to connect this way.

Admin API key — a static key set via the API_KEY environment variable in your Runner configuration. It grants access to executor management and run operations, and is primarily used by executors to register, send heartbeats, claim runs, and post logs. Pass it using the same ApiKey scheme:

Authorization: ApiKey <api-key>

JWT bearer tokens — used internally by the Runner web UI after login. The Authorization: Bearer <token> scheme is accepted but tokens are short-lived (7 days) and not designed for external use.

Further integrations

NodePit Runner for KNIME is a KNIME extension that lets you interact with Runner directly from within KNIME Analytics Platform, both via dedicated nodes and through the KNIME Explorer panel.

AI Assistant (MCP Server) lets an AI assistant such as Claude or ChatGPT call this API on your behalf through the Model Context Protocol, instead of you writing requests by hand.