docs

Sessions

A session is a working copy of a detected form. Fill it conversationally, with deterministic per-field actions, or with direct structured values — then render and download the finished PDF.

Create a session

POST/sessionsBearer auth

Open a session over a previously created form. Returns 201 with the session_id.

Parameters

NameInTypeRequiredDescription
form_idbodystringyesThe form to open a session over.

Status codes

  • 201Session created.
  • 400Missing or invalid form_id.
  • 401Missing or invalid API key.
  • 404No such form, or owned by another key.
curl -X POST https://api.getemboss.ai/sessions \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"form_id":"form_3d9a"}'
Response
{
  "session_id": "sess_a1b2",
  "status": "open"
}

Get session state

GET/sessions/{id}Bearer auth

Read the current state of a session and its fields.

Parameters

NameInTypeRequiredDescription
idpathstringyesThe session_id.

Status codes

  • 200The session state.
  • 401Missing or invalid API key.
  • 404No such session, or owned by another key.
curl https://api.getemboss.ai/sessions/sess_a1b2 \
  -H "Authorization: Bearer sk_live_yourkey"
Response
{
  "session_id": "sess_a1b2",
  "status": "open",
  "fields": [
    { "id": "f_001", "label": "Business name", "value": "Analytical Engines LLC", "state": "confirmed" }
  ]
}

Conversational turn

POST/sessions/{id}/turnsBearer auth

Send a message to fill fields conversationally. Uses an LLM to interpret the turn against the form.

Parameters

NameInTypeRequiredDescription
idpathstringyesThe session_id.
messagebodystringyesThe user's natural-language message.

Status codes

  • 200The assistant reply and updated field ids.
  • 401Missing or invalid API key.
  • 404No such session, or owned by another key.
  • 409Session is completed (terminal).
  • 429Rate limited.
curl -X POST https://api.getemboss.ai/sessions/sess_a1b2/turns \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"message":"My EIN is 12-3456789 and I am an LLC."}'
Response
{
  "reply": "Got it — set the EIN and tax classification.",
  "updated": ["f_002", "f_007"]
}

Confirm a field

POST/sessions/{id}/confirmBearer auth

Deterministically confirm a proposed field value. No LLM involved.

Parameters

NameInTypeRequiredDescription
idpathstringyesThe session_id.
field_idbodystringyesThe field to confirm.

Status codes

  • 200Field confirmed.
  • 401Missing or invalid API key.
  • 404No such session/field, or owned by another key.
  • 409Session is completed (terminal).
curl -X POST https://api.getemboss.ai/sessions/sess_a1b2/confirm \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"field_id":"f_001"}'

Skip a field

POST/sessions/{id}/skipBearer auth

Deterministically mark a field as skipped. No LLM involved.

Parameters

NameInTypeRequiredDescription
idpathstringyesThe session_id.
field_idbodystringyesThe field to skip.

Status codes

  • 200Field skipped.
  • 401Missing or invalid API key.
  • 404No such session/field, or owned by another key.
  • 409Session is completed (terminal).
curl -X POST https://api.getemboss.ai/sessions/sess_a1b2/skip \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"field_id":"f_009"}'

Decline a field

POST/sessions/{id}/declineBearer auth

Deterministically decline a proposed value, clearing it. No LLM involved.

Parameters

NameInTypeRequiredDescription
idpathstringyesThe session_id.
field_idbodystringyesThe field to decline.

Status codes

  • 200Field declined.
  • 401Missing or invalid API key.
  • 404No such session/field, or owned by another key.
  • 409Session is completed (terminal).
curl -X POST https://api.getemboss.ai/sessions/sess_a1b2/decline \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"field_id":"f_005"}'

Direct field fill

PUT/sessions/{id}/fieldsBearer auth

Set field values directly by id — a structured, deterministic fill with no LLM.

Parameters

NameInTypeRequiredDescription
idpathstringyesThe session_id.
fieldsbodyarray<{id, value}>yesField ids and the values to set.

Status codes

  • 200Fields set.
  • 400Unknown field id or invalid value type.
  • 401Missing or invalid API key.
  • 404No such session, or owned by another key.
  • 409Session is completed (terminal).
curl -X PUT https://api.getemboss.ai/sessions/sess_a1b2/fields \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"fields":[{"id":"f_001","value":"Analytical Engines LLC"},{"id":"f_007","value":true}]}'
Response
{
  "updated": ["f_001", "f_007"]
}

Render the filled PDF

POST/sessions/{id}/fillBearer auth

Render the session's confirmed values into a filled PDF and mark it completed.

Parameters

NameInTypeRequiredDescription
idpathstringyesThe session_id.

Status codes

  • 200Filled; session is now completed.
  • 401Missing or invalid API key.
  • 404No such session, or owned by another key.
  • 409Session is already completed (terminal).
curl -X POST https://api.getemboss.ai/sessions/sess_a1b2/fill \
  -H "Authorization: Bearer sk_live_yourkey"
Response
{
  "session_id": "sess_a1b2",
  "status": "completed"
}

Download the PDF

GET/sessions/{id}/pdfBearer auth

Download the rendered PDF. The response body is the raw %PDF bytes.

Parameters

NameInTypeRequiredDescription
idpathstringyesThe session_id.

Status codes

  • 200The PDF bytes (application/pdf).
  • 401Missing or invalid API key.
  • 404No such session, or owned by another key.
  • 409Session has not been filled yet.
curl https://api.getemboss.ai/sessions/sess_a1b2/pdf \
  -H "Authorization: Bearer sk_live_yourkey" \
  -o filled.pdf
Response
%PDF-1.7
…binary…