How it works
Overview of the API requests Looking Glass makes to your backend, and how to use them effectively with session-aware retrieval.
API Requests
The extension requests ground-truth values from your backend for fields described by a JSON Schema. Each request includes identifiers that let you correlate activity with your own tasks and maintain state across a session.
- Inputs:
session_id
,task_id
, and a JSON Schema describing the field(s) to retrieve. - Output: A JSON object with values keyed by schema field, plus echoing identifiers you wish to persist.
// Example request payload
{
"session_id": "<uuid generated by Looking Glass>",
"task_id": "<uuid you generated for this task>",
"form_schema": {
"type": "object",
"properties": {
"full_name": {
"type": "string"
},
"account_opened": {
"type": "string",
"format": "date"
}
},
"required": ["full_name", "account_opened"]
}
}
// Example response payload
{
"full_name": "Jane Doe",
"account_opened": "2024-01-01"
}
Task ID
First is task_id
. This is an ID you generate to correlate a session run in the extension with an entity in your backend.
For example, if a workflow is "Fill out form <x> for customer <y>", you'll have a UUID in your backend when that task is created. Operators can pass this to the extension when the session starts.
Session ID
Second is session_id
. This is an ID Looking Glass generates. It will be the same for all requests in a session. You'll receive the session_id
in every request to your backend. You can use this to track state in your backend retrieval.
Session Start
When the session starts in the extension, it will call POST /start
on your backend with the task_id
and session_id
. This endpoint is required. The extension will not scan a page until this succeeds.
{
"task_id": "123e4567-e89b-12d3-a456-426614174000",
"session_id": "b7e3a2c0-4f1a-4e2a-9c3d-8f2e4b1a5c6d"
}
You can use this to retrieve supplemental information for the task from your backend to show to the operator.
Example
Your backend will receive
{
"task_id": "123e4567-e89b-12d3-a456-426614174000",
"session_id": "b7e3a2c0-4f1a-4e2a-9c3d-8f2e4b1a5c6d"
}
You respond with:
{
"session_id": "b7e3a2c0-4f1a-4e2a-9c3d-8f2e4b1a5c6d",
"supplemental_information": {
"Name": "John Doe",
"Age": 30,
"Address": "123 Main St, Anytown, USA"
},
"task_labels": ["priority:high", "segment:consumer"]
}
The operator will see this data in the extension, so that it's easy for them to provide the correct information in the event the retrieval is incorrect.
Session State
In your backend, you can use the session_id
to track the state of the session.
Example
Operator is doing form filing <x> for a customer <y>.
The first field on the first page is "Education Level". You get a request like this:
{
"session_id": "b7e3a2c0-4f1a-4e2a-9c3d-8f2e4b1a5c6d",
"task_id": "123e4567-e89b-12d3-a456-426614174000",
"form_schema": {
"type": "object",
"properties": {
"education": {
"type": "string",
"enum": ["high school", "associates", "bachelors", "masters", "phd"],
"description": "Education level"
}
},
"required": ["education"]
}
}
You respond with:
{
"education": "bachelors"
}
Then the next request you get is:
{
"session_id": "b7e3a2c0-4f1a-4e2a-9c3d-8f2e4b1a5c6d",
"task_id": "123e4567-e89b-12d3-a456-426614174000",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
}
},
"required": ["name"]
}
}
Here, it's not obvious whether this should be the name of the individual or the name of the school they went to. With the session_id
, you can track the state of the session and use it to make a better guess. Since the previous request was for "education", you can assume this is the name of the school they went to.
{
"name": "Harvard University"
}
See also: Quickstart and Evaluate.