​
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.

​
Submit a form response (widget-side)

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.
AuthJWT bearer or X-API-Key (see API Keys)
ScopingStaff 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

ParameterDescription
session_idFilter by session ID.
form_idFilter 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.