> ## Documentation Index
> Fetch the complete documentation index at: https://requestscript.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API

> Every endpoint for running scripts and managing contracts.

A RequestScript server exposes these endpoints. Examples use `http://localhost:3000` as the server address. Your server may also require authentication headers; ask its administrator.

| Method and path | Body | Purpose |
| - | - | - |
| `POST /run` | Script text | Run a `request` script once |
| `POST /contracts` | Script text | Save a `contract` script |
| `POST /run/<path>/<Name>` | `{ "parameters": { ... } }` | Invoke the latest version of a contract |
| `POST /run/<path>/<Name>@<version>` | `{ "parameters": { ... } }` | Invoke a specific version of a contract |
| `GET /contracts` | None | List every saved contract version |
| `DELETE /contracts/<path>/<Name>` | None | Delete every version of a contract |
| `DELETE /contracts/<path>/<Name>@<version>` | None | Delete one version of a contract |

In URLs, the dots of a contract's path become slashes: `shop.orders.LineTotal` is `/run/shop/orders/LineTotal`.

## Run a request

`POST /run`

Runs a `request` script once. Send the script source as the request body.

```bash theme={null}
curl -X POST http://localhost:3000/run \
  --data-binary @- <<'EOF'
request HelloWorld {
    return "Hello World!"
}
EOF
```

**Response `200`**

```json theme={null}
{ "returnValue": "Hello World!" }
```

Sending a `contract` script to this endpoint is rejected with `400 InvalidScript`.

## Save a contract

`POST /contracts`

Saves a `contract` script. Send the script source as the request body.

```bash theme={null}
curl -X POST http://localhost:3000/contracts \
  --data-binary @- <<'EOF'
contract path.to.MyContract@2(param1: string) {
    return "Hello ${param1}!"
}
EOF
```

**Response `201`**

```json theme={null}
{
  "path": "path.to",
  "name": "MyContract",
  "version": "2",
  "parameters": [{ "name": "param1", "type": "string" }]
}
```

* `409 ContractExists` if that path, name and version is already saved.
* `400 InvalidScript` if the script is a `request` rather than a `contract`.

## Invoke a contract

`POST /run/<path>/<Name>` or `POST /run/<path>/<Name>@<version>`

Runs a saved contract. Without a version, the latest version runs. Send parameters as JSON under `parameters`. For a contract without parameters, send `{}` or no body.

```bash theme={null}
curl -X POST http://localhost:3000/run/path/to/MyContract@2 \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "param1": "World" } }'
```

**Response `200`**

```json theme={null}
{ "returnValue": "Hello World!" }
```

See [Invoking contracts](/contracts/invoking) for how parameters are converted.

## List contracts

`GET /contracts`

Lists every saved version of every contract.

**Response `200`**

```json theme={null}
{
  "contracts": [
    {
      "path": "path.to",
      "name": "MyContract",
      "version": "2",
      "parameters": [{ "name": "param1", "type": "string" }]
    }
  ]
}
```

## Delete a contract

`DELETE /contracts/<path>/<Name>` or `DELETE /contracts/<path>/<Name>@<version>`

Without a version, deletes every version of the contract. With a version, deletes only that version.

**Response `204`** with no body.

## Errors

Every error response has the same shape:

```json theme={null}
{
  "error": {
    "type": "ParseError",
    "message": "A parameter list must not be empty; omit the parentheses instead (line 1)"
  }
}
```

| Status | `type` | Meaning |
| - | - | - |
| `400` | `LexError` | The script contains invalid characters, strings or escapes. |
| `400` | `ParseError` | The script isn't valid RequestScript. |
| `400` | `ParameterError` | A contract parameter is missing, unknown or has the wrong type. |
| `400` | `InvalidScript` | A `contract` was sent to `/run`, or a `request` was sent to `/contracts`. |
| `400` | `InvalidVersion` | The version after `@` in the URL isn't dot-separated numbers. |
| `400` | `InvalidBody` | The body isn't valid JSON, isn't a JSON object, or `parameters` isn't an object. |
| `404` | `UnknownContract` | No contract matches the path, name and version. |
| `404` | `NotFound` | No endpoint matches the method and URL. |
| `409` | `ContractExists` | That contract version is already saved. |
| `422` | `RuntimeError` | The script failed while running. |

See [Errors](/language/errors) for what causes script errors. A failing [resource](/resources/results) call is not an error response: it's reported to the script, and the request still succeeds.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.