REST API Reference

Getting Started


The Pup REST API employs JWT (JSON Web Token) authentication to secure its endpoints. Before proceeding, you'll need to acquire a valid JWT. This is done by running pup token --consumer <consumer-name> at the command line, you can also provide --expire-in <seconds>.

A token can be revoked through the api section of pup.json.

Authorization Header

Include your JWT in the Authorization header for every API request:

Authorization: Bearer <your_jwt_token>

Base URL

The base URL for all Pup REST API endpoints is as follows. Replace hostname and port with the actual values where your Pup REST API is running.



Process Management

  • GET /processes Retrieves a list of all managed processes and their current states.

  • POST /processes/{id}/start Starts a process with the specified ID.

  • POST /processes/{id}/stop Stops a process with the specified ID.

  • POST /processes/{id}/restart Restarts a process with the specified ID.

  • POST /processes/{id}/block Blocks a process with the specified ID, preventing automatic restarts.

  • POST /processes/{id}/unblock Unblocks a previously blocked process with the specified ID.

Application State

  • GET /state Fetches the current overall state of the Pup application


  • POST /telemetry Submits telemetry data to the Pup main instance.


  • POST /log Sends a log message to the Pup instance.

  • GET /logs Retrieves logs, supporting filtering by criteria such as process ID, severity, and timeframe.


  • POST /terminate Initiates a shutdown of the Pup application

Error Handling

The Pup REST API uses standard HTTP status codes to communicate success or failure of requests. Common error codes include:

  • 400 (Bad Request): Invalid input data or request syntax.
  • 401 (Unauthorized): Missing or invalid JWT.
  • 403 (Forbidden): The provided JWT lacks required permissions.
  • 500 (Internal Server Error): Unexpected errors on the server side.

Example Usage (JavaScript)

const response = fetch("/api/processes", {
  headers: {
    "Authorization": "Bearer your_jwt_token",
const responseData = await response.json()

Note: Replace your_jwt_token with your actual JWT.