Form Responses

Overview

When a form’s submit_url is set to null, the widget stores submissions in Oshara’s managed storage. You can retrieve them via the API after the call.

The widget calls this automatically — you don’t need to call it yourself unless you’re building a custom integration.


POST /api/agents/{slug}/form-responses/

Request body:


{
  "form_id": "book-demo",
  "session_id": "sess_a1b2c3",
  "values": {
    "first_name": "Alice",
    "email": "alice@example.com",
    "date": "2025-06-15"
  }
}

Response: 201 Created

List form responses


GET /api/agents/{slug}/form-responses/

Returns all form submissions for a character.


Auth	JWT bearer or `X-API-Key` (see API Keys)
Scoping	Staff see all responses. All other callers must be the creator of the character (`AICharacter.created_by`); requests for other people’s characters return `403`.


# Using an API key
curl https://api.oshara.ai/api/agents/support-bot/form-responses/ \
  -H "X-API-Key: sk_..."
 
# Or using a JWT
curl https://api.oshara.ai/api/agents/support-bot/form-responses/ \
  -H "Authorization: Bearer <token>"

Query parameters

Parameter	Description
`session_id`	Filter by session ID.
`form_id`	Filter by form ID (e.g. `book-demo`).

Response


[
  {
    "id": 42,
    "form_id": "book-demo",
    "session_id": "sess_a1b2c3",
    "values": {
      "first_name": "Alice",
      "email": "alice@example.com",
      "date": "2025-06-15"
    },
    "created_at": "2025-06-10T14:23:00Z"
  }
]

Filter by form and session


curl "https://api.oshara.ai/api/agents/support-bot/form-responses/?form_id=book-demo&session_id=sess_a1b2c3" \
  -H "Authorization: Bearer <token>"

Using a custom submit URL instead

If you’d rather receive submissions directly at your own endpoint, set submit_url to an absolute URL in the form definition:


{
  "id": "book-demo",
  "submit_url": "https://api.yoursite.com/demo-requests",
  "fields": [...]
}

The widget will POST the values object as JSON to that URL. Return any 2xx to confirm success. In this case, nothing is stored in Oshara.