# Forms API

> [!WARNING]
> This API is in alpha preview, and may be changed or removed in the future.

Progressive disclosure of form fields and validation of form data is supported by our Forms Interaction API.

[The Transport Demo Agent](/agents/demo/transport#code) illustrates how to use this feature;
please click on the _Code_ tab to see this Agent's YAML code, and note its [JSON Schema](https://json-schema.org) embedded in `output.schema.properties`.

[Create an API Key](api-key.md) to use the [Forms _Preview_ API](/docs/api?specs=form), e.g. with `curl`:

```bash
curl --no-progress-meter -X 'POST' 'https://api.aish.li/v1/form?agent=demo%2Ftransport' \
  -H 'X-API-Key: sk_...' \
  | jq .
```

returns:

```json
{
  "sessionID": "uXxvDmOLaYkGU0qIMpd359Q",
  "mapForm": {
    "nextQuestion": "Do you need a ride? Just let me know your origin, destination, day and time you're interested in!\n",
    "isFormComplete": false
  }
}
```

You can then use the returned `sessionID` to submit the user's input and progressively validate or disclose remaining fields, e.g.:

```bash
curl --no-progress-meter -X 'POST' \
  'https://api.aish.li/v1/form/uXxvDmOLaYkGU0qIMpd359Q?agent=demo%2Ftransport' \
  -H 'X-API-Key: sk_...' \
  -d 'John Doe, from Novello to Barolo' \
  | jq .
```

which will return:

```json
{
  "sessionID": "uXxvDmOLaYkGU0qIMpd359Q",
  "mapForm": {
    "data": {
      "origin_longitude": 7.9258,
      "origin_date_time": "2026-09-26T15:09Z",
      "destination_latitude": 44.6104,
      "origin": "Novello",
      "name": "John Doe",
      "destination": "Barolo",
      "destination_longitude": 7.9414,
      "origin_latitude": 44.5894
    },
    "isFormComplete": true
  }
}
```