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

# Apply filing session event

Applies one event to a filing session and returns the resulting form. Events set
a field, invoke an action such as advancing to the next step, or search the
values of a field.

This operation authenticates with the session token returned by [create filing
session](/api-reference/filing-sessions/create-filing-session), not an API key.
See [session tokens](/api-reference/introduction#session-tokens).

## Request

<ParamField body="state_version" type="integer" required>
  The state version of the session that this event applies to. Use the
  `state_version` from your most recent response.
</ParamField>

<ParamField body="event" type="object" required>
  The event to process. It has a `kind` that selects one of the shapes below.

  <Expandable title="set_field">
    Sets the value of a field. This does not advance to the next step.

    <ParamField body="kind" type="string" required>
      `set_field`.
    </ParamField>

    <ParamField body="field" type="string" required>
      The `key` of the field to set.
    </ParamField>

    <ParamField body="value" type="any" required>
      The new value, in the representation given by the field's `ty`. For a
      field with options, use the `value` of one of the options exactly as
      given. A document is set with an object; see
      [files](/api-reference/filing-sessions/form#files).
    </ParamField>
  </Expandable>

  <Expandable title="action">
    Invokes one of the actions on the form, such as submitting the current step
    and advancing.

    <ParamField body="kind" type="string" required>
      `action`.
    </ParamField>

    <ParamField body="action_id" type="string" required>
      The `action_id` of the action to invoke.
    </ParamField>
  </Expandable>

  <Expandable title="search">
    Searches the values of a field that has `search`. This does not set the
    field's value. See [search](/api-reference/filing-sessions/form#search).

    <ParamField body="kind" type="string" required>
      `search`.
    </ParamField>

    <ParamField body="field" type="string" required>
      The `key` of the field to search.
    </ParamField>

    <ParamField body="query" type="string" required>
      The text to search for. If empty, the response contains a default
      selection of results.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="form" type="object">
  The form to render after the event was applied. See the [form
  reference](/api-reference/filing-sessions/form).
</ResponseField>

<ResponseField name="state_version" type="integer">
  The new state version of the session. Use it for your next request.
</ResponseField>

## Concurrency

A session handles one event at a time, and every event names the state version
it was based on. This keeps two clients, or a client and a retry, from
overwriting each other. If a request fails after you sent it and you cannot tell
whether it was applied, send it again with the same `state_version`: if it was
applied the session has moved on, and you get `stale_state` with the current
form instead of a second application.

## Errors

<ResponseField name="not_found">The session no longer exists.</ResponseField>

<ResponseField name="session_busy">
  Another request for this session is in progress. Wait briefly and retry the
  same event.
</ResponseField>

<ResponseField name="stale_state">
  The `state_version` did not match the session's current version. The error
  includes the current `form` and `state_version`. Use those rather than
  retrying blindly, since the field or action you intended may no longer apply.
</ResponseField>

<ResponseField name="session_expired">
  The session has expired. This is terminal.
</ResponseField>

## Example

```shell Request theme={null}
curl -X POST https://api.rhetoric.law/apply-filing-session-event \
  --header "Authorization: Bearer $SESSION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "state_version": 1,
    "event": {
      "kind": "set_field",
      "field": "court_system",
      "value": "illinois"
    }
  }'
```

```json Response theme={null}
{
  "result": "ok",
  "form": {
    "title": "Select a court system",
    "blocks": [
      {
        "id": "field_group:court_system",
        "items": [
          {
            "kind": "field",
            "key": "court_system",
            "label": "Court system",
            "description": "The court system where your case will be filed.",
            "required": true,
            "disabled": false,
            "sensitive": false,
            "ty": "string",
            "options": [
              { "value": "california", "label": "California" },
              { "value": "illinois", "label": "Illinois" }
            ],
            "validations": [],
            "value": "illinois",
            "errors": []
          }
        ],
        "actions": []
      }
    ],
    "actions": [{ "action_id": "next", "label": "Next", "primary": true }],
    "breadcrumbs": ["Start filing", "Select a court system"],
    "errors": []
  },
  "state_version": 2
}
```

```json Stale state theme={null}
{
  "result": "err",
  "code": "stale_state",
  "form": { "title": "Select a court system", "...": "..." },
  "state_version": 3
}
```


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