> 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
### 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 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](#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 %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://bugpilot.gitbook.io/api-docs/http-api/api-reference/actions.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.