# The Loadster REST API

> Call the Loadster REST API with a personal access token to manage scripts, scenarios, monitors, and load test results, or launch load tests from CI.

Source: https://loadster.com/manual/rest-api/

The Loadster REST API lets your own scripts and tools work with the same projects, scripts, scenarios, datasets,
monitors, and load test results you see in the dashboard. It's handy for automating the setup around your load tests,
pulling test reports into other systems, or pausing monitors during a deployment.

If you're connecting an AI assistant, the [Loadster MCP server](https://loadster.com/manual/ai-agents/) is usually a better fit, since it
gives the assistant tools built for the job. And if all you need is to launch a load test from a CI pipeline, a
scenario's [trigger URL](https://loadster.com/manual/load-testing-with-continuous-integration/) is simpler still.

## The Loadster OpenAPI Spec

Every public endpoint is described in an OpenAPI spec at
[https://api.loadster.com/openapi.json](https://api.loadster.com/openapi.json). You can import it into Postman,
Insomnia, or any other tool that reads OpenAPI to browse the endpoints and request shapes, or generate a client from
it. AI coding agents can read it too.

The spec covers the endpoints we support for outside callers. The dashboard calls other endpoints as well, but those
aren't part of the public API, and they can change without notice.

## Creating a Personal Access Token for the Loadster API

The REST API authenticates with a personal access token.

1. In the Loadster dashboard, go to **Settings → API & Agents → Personal Access Tokens**.
2. Give the token a name that says where you'll use it (like "GitHub Actions") and create it.
3. Copy the token right away, since it's only shown once.

A personal access token acts as you within the team where you created it, so treat it like a password. Keep it in
your CI system's secrets or a password manager rather than in your code, and revoke any tokens you no longer use.
Revoking a token cuts off anything using it right away.

The same token works with the [Loadster MCP server](https://loadster.com/manual/ai-agents/), but it can't reach the rest of your account.
It only works with the endpoints in the OpenAPI spec, so it can't change your password, billing, or team members.

## Making Requests to the Loadster REST API

Send the token as a bearer token in the `Authorization` header. For example, to list your projects:

```text
$ curl https://api.loadster.com/projects -H "Authorization: Bearer YOUR_TOKEN"
```


Requests and responses are JSON. Most things belong to a project, so paths usually start with the project's ID, like
`/projects/a83sf61/scripts`. You can find the project ID in the dashboard's URL when you open the project.

Updates use `PATCH`, and you send only the fields you want to change. For example, to rename a load test:

```text
$ curl -X PATCH https://api.loadster.com/projects/a83sf61/tests/t4k9m2xqz \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "Release 4.2 baseline"}'
```


## Loadster API Errors and Rate Limits

When something goes wrong, the API answers with a 4xx or 5xx status and a JSON body with a `message` describing the
problem. A `401` or `403` usually means the token is missing, mistyped, or revoked, or that the endpoint isn't part of
the public API.

A `403` can also mean your team requires two-factor authentication and you haven't set it up yet. Your tokens stop
working until you do, and work again as soon as you've set it up in the Loadster dashboard.

Some endpoints are rate limited, and they answer `429 Too Many Requests` if you call them too often. If that happens,
wait a little while before trying again.

## Launching Load Tests from CI without a Token

The trigger endpoints are the one part of the API that doesn't need a token. A `POST` to a scenario's trigger URL
launches a load test, and the response includes status and report URLs you can poll until it finishes. The code in
each URL is what authorizes the request, so treat it like a password too. The
[continuous integration](https://loadster.com/manual/load-testing-with-continuous-integration/) page walks through it with curl and the
[Loadster CLI](https://loadster.com/manual/loadster-cli/).