# JSON API or File

Connect to product analytics or dashboard endpoints that expose JSON. The plugin uses a proxy to make requests, map nested arrays, and convert them into chart-ready series.

### When to use it

* You have an HTTP endpoint returning JSON data.
* You need to authenticate with a bearer token or custom headers.
* Your data lives in nested arrays and you want to pick which keys become categories and series.

### Request setup

1. Switch to **Data Source → JSON** and choose the `API` mode.
2. Enter the **URL** and choose the HTTP **Method** (`GET` or `POST`).
3. If authentication is needed:
   * `Bearer` — paste the token; the plugin adds the header.
   * `Custom headers` — paste a JSON object (e.g. `{ "X-API-Key": "123" }`).
4. Optional: add request parameters or body. Provide a JSON object.

### Selecting data

1. Click **Fetch** to send the request through the proxy.
2. After a successful response, pick the array path containing your records (e.g. `<root>`, `data.items`).
3. Choose the **Category field** (x-axis labels) and one or more **Value fields** (series). The preview updates as soon as selections are made.

### Tips

* Test the endpoint in Postman or a browser first to confirm the response shape.
* Avoid extremely large payloads—paginate on the server side if possible.

### Troubleshooting

| Error banner                             | Meaning                                     | Fix                                                                       |
| ---------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
| “Request parameters must be valid JSON.” | Invalid JSON in headers/body.               | Validate with a formatter and try again.                                  |
| “Failed to fetch JSON data.”             | Network error, auth failure, or CORS block. | Check the HTTP status in the console/log banner and confirm credentials.  |
| Preview array list is empty              | Response doesn’t contain arrays of objects. | Check the array path and ensure the endpoint returns an array of records. |

### Security note

The proxy forwards your request payload and headers to `https://chart-plugin.com/proxy`. Avoid sending highly sensitive data or credentials unless you trust the endpoint owner.