> For the complete documentation index, see [llms.txt](https://bugpilot.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bugpilot.gitbook.io/api-docs/http-api/api-reference/actions.md). # 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](https://docs.bugpilot.io/en/articles/6389274-installing-the-bugpilot-script). 2. You need to [set up user identification](https://docs.bugpilot.io/en/articles/6389274-installing-the-bugpilot-script) and send either a user ID or an email to Bugpilot. 3. In [Bugpilot API Settings](https://dash.bugpilot.io/settings/api), 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 nameDescription
show-recording-uiShows 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-screenshotRequests 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-sessionRequests 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](#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](https://dash.bugpilot.io/settings/api). | | 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](https://dash.bugpilot.io/settings/api). | | 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](#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. | {% tabs %} {% tab title="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. ```json { "ok": true, "message": "The request has been sent to the client", "ts": 1669738581021, "sessionInfoUrl": "https://widget-api.bugpilot.io/api/v1/session-info/*****/*****" } ``` {% endtab %} {% tab title="401: Unauthorized The API Key is missing or invalid." %} {% code overflow="wrap" %} ```json { "error": "INVALID_API_KEY", "error_message": "Please verify that provided api key is valid", "ts": 1669375385570 } ``` {% endcode %} {% endtab %} {% tab title="400: Bad Request One or more required fields are missing." %} {% code overflow="wrap" %} ```json { "error": "MISSING_FIELDS", "error_message": "Required fields are missing", "ts":1669374482889 } ``` {% endcode %} {% endtab %} {% tab title="400: Bad Request Invalid action. Check allowed values." %} ```json { "error": "INVALID_ACTION", "error_message": "Please verify that provided action is valid", "ts": 1669374622023 } ``` {% endtab %} {% tab title="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](https://dash.bugpilot.io/settings/api). Once you change this option, it will become effective the next time users will load a page. **Error example** ```json { "error": "USER_NOT_CONNECTED", "error_message": "The user is not connected to Bugpilot", "ts":1669374994818 } ``` {% endtab %} {% tab title="403: Forbidden Check that the request path is correct." %} ```json { "error":"NO_ACCESS", "error_message": "You don't have access to this resource", "ts": 1669375568120 } ``` {% endtab %} {% tab title="500: Internal Server Error Something is wrong on our end. Contact us." %} ```json { "error": "INTERNAL_ERROR", "error_message": "The request cannot be processed due to an internal error", "ts": 1669375835566 } ``` {% endtab %} {% endtabs %} #### Example {% tabs %} {% tab title="curl" %} ```bash curl \ -X POST \ -H "Content-Type: application/json" \ -H "User-Agent: Bugpilot API Client/1.0" \ -H "X-Bugpilot-Api-Key: " \ -d '{ "workspaceId": "", "userId": "end-user-id", "action": "upload-session" }' \ https://widget-api.bugpilot.io/api/v1/action ``` {% endtab %} {% tab title="Node.js" %} ```javascript 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": "", }, body: JSON.stringify({ workspaceId: "", 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+)* {% endtab %} {% tab title="Python" %} ```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": "", }, json={ "workspaceId": "", "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 ``` {% endtab %} {% endtabs %}