Actions

The Actions endpoint allows you to request Bugpilot reports from your end users.

Prerequisites

To successfully execute a Bugpilot action:

1. You need to install the Bugpilot script.

2. You need to set up user identification and send either a user ID or an email to Bugpilot.

3. In Bugpilot API Settings, make sure the Always connect Action WebSockets, is selected. It is not selected by default.

4. The end-user needs to be online on one of your pages at the time you call the API. If the user is not online, the requests will fail with an USER_NOT_CONNECTED error.

Available actions

This table lists the operations that can be performed using this API endpoint.

Action name	Description
show-recording-ui	Shows a UI to the user that can be used to submit up to 60 seconds of screen recording. The user will see a recording frame and a button to stop the recording earlier.
upload-screenshot	Requests a Bugpilot report with a screenshot of the page the user is currently seeing. No UI will be shown to the user when performing this action.
upload-session	Requests a Bugpilot report with a recording of the last 5-10 minutes of user activity. No UI will be shown to the user when performing this action.

Endpoints

Executes an action on the end-users

POST https://widget-api.bugpilot.io/api/v1/action

See Available Actions for the list of actions you can perform with this endpoint.

Headers

Name	Type	Description
user-agent*	string	Bugpilot API Client/1.0
x-bugpilot-api-key*	string	The Workspace API Key that you can find in your Bugpilot dashboard.
content-type*	string	application/json

Request Body

Name	Type	Description
workspaceId*	string	The ID of your workspace. You can find it in your Bugpilot dashboard.
userId*	string	The ID (or email) of the end-user which Bugpilot will perform the specified action on. The user ID must match the user ID you pass to the Bugpilot.identify() method on the client.
action*	string	Action you want Bugpilot to perform on the end-user. Must be one of the Available Actions listed above.
userProvidedDescription	String	An optional string containing a description text. It will be saved in the report object and shown on the report page under the Notes section.

200: OK Action executed successfully.

The response contains ok: true if it is successful. In any case, a sessionInfoUrl property is included. Refer to the Session Info API reference for further information.

{
    "ok": true,
    "message": "The request has been sent to the client",
    "ts": 1669738581021,
    "sessionInfoUrl": "https://widget-api.bugpilot.io/api/v1/session-info/*****/*****"
}

401: Unauthorized The API Key is missing or invalid.

{ 
    "error": "INVALID_API_KEY",
    "error_message": "Please verify that provided api key is valid",
    "ts": 1669375385570
}

400: Bad Request One or more required fields are missing.

{
    "error": "MISSING_FIELDS",
    "error_message": "Required fields are missing",
    "ts":1669374482889
}

400: Bad Request Invalid action. Check allowed values.

{
    "error": "INVALID_ACTION",
    "error_message": "Please verify that provided action is valid",
    "ts": 1669374622023
}

400: Bad Request The end-user is not connected to Bugpilot; for example, the user is not currently online.

This error occurs when the user is offline or does not have any of your web app's pages open.

Make sure Always connect Action WebSockets is selected in Bugpilot API Settings. Once you change this option, it will become effective the next time users will load a page.

Error example

{
    "error": "USER_NOT_CONNECTED", 
    "error_message": "The user is not connected to Bugpilot", 
    "ts":1669374994818
}

403: Forbidden Check that the request path is correct.

{
    "error":"NO_ACCESS", 
    "error_message": "You don't have access to this resource", 
    "ts": 1669375568120
}

500: Internal Server Error Something is wrong on our end. Contact us.

{ 
    "error": "INTERNAL_ERROR", 
    "error_message": "The request cannot be processed due to an internal error", 
    "ts": 1669375835566
}

Example

curl

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "User-Agent: Bugpilot API Client/1.0" \
  -H "X-Bugpilot-Api-Key: <ID FROM BUGPILOT API SETTINGS>" \
  -d '{
    "workspaceId": "<WORKSPACE ID FROM BUGPILOT API SETTINGS>",
    "userId": "end-user-id",
    "action": "upload-session"
  }' \
  https://widget-api.bugpilot.io/api/v1/action

Node.js

const result = await fetch("https://widget-api.bugpilot.io/api/v1/action", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "User-Agent": "Bugpilot API Client/1.0",
    "X-Bugpilot-Api-Key": "<ID FROM BUGPILOT API SETTINGS>",
  },
  body: JSON.stringify({
    workspaceId: "<WORKSPACE ID FROM BUGPILOT API SETTINGS>",
    userId: "end-user-id",
    action: "upload-session",
  }),
});

if (!result.ok) {
  throw new Error(`Bugpilot API error: ${result.status} ${result.statusText}`);
}

const body = await result.json();

// body.ok is true if the operation was successful
// body.error and body.error_message are strings if the operation failed

(this example requires node.js 18+)

Python

r = requests.post(
    "https://widget-api.bugpilot.io/api/v1/action",
    headers={
        "Content-Type": "application/json",
        "User-Agent": "Bugpilot API Client/1.0",
        "X-Bugpilot-Api-Key": "<ID FROM BUGPILOT API SETTINGS>",
    },
    json={
        "workspaceId": "<WORKSPACE ID FROM BUGPILOT API SETTINGS>",
        "userId": "end-user-id",
        "action": "upload-session",
    },
)

r.raise_for_status()

body = r.json()

# body.ok is true if the operation was successful
# body.error and body.error_message are strings if the operation failed