Api Overview¶

The service exposes a small HTTP Api under the /api/v1 prefix. In the DataGEMS development deployment it is reachable at https://datagems-dev.scayle.es/qr/api/v1. All request and response bodies are JSON.

The full, machine readable description is available in the OpenAPI Reference. A running instance also serves it at:

/api/v1/openapi.json: the OpenAPI document
/api/v1/swagger: Swagger UI
/api/v1/redoc: ReDoc

Endpoints¶

Method	Path	Auth	Description
GET	`/api/v1`	no	Api root: confirms the Api is running and lists the endpoints
POST	`/api/v1/recommend-next-queries`	yes	Recommends the next queries for the current one
POST	`/api/v1/authtest`	yes	Checks that a bearer token is accepted by the service

GET / redirects to /api/v1.

POST /api/v1/recommend-next-queries

Request¶

Field	Type	Required	Description
`current_query`	string	yes	The natural language query the user has just submitted
`context`	object or null	no	Additional information about the request. Currently only `context.user_id` is used

context.user_id is the User Profiler identifier of the user submitting the query. When present, the user's interest keywords are used to personalise the suggestions. When it is missing, null, or does not match a known user, the suggestions depend on the current query only. Other fields in context are accepted and ignored. They are reserved for future use, such as a summary of the current query's results.

{
  "current_query": "What is there to do in Verona tonight?",
  "context": {
    "user_id": "user1"
  }
}

An anonymous request can omit context altogether:

{
  "current_query": "Average rainfall in northern Italy"
}

Response¶

Field	Type	Description
`next_queries`	array of strings	The suggested next queries, most useful first

{
  "next_queries": [
    "Concerts in Verona this weekend",
    "Opera at the Arena di Verona",
    "Late night restaurants in Verona"
  ]
}

The service asks for 3 suggestions and returns at most 3. It can return fewer: suggestions that are empty, duplicated, or identical to the current query (ignoring case and surrounding spaces) are dropped. Clients should not assume exactly 3 entries, and should handle an empty list.

Recommendations are generated by an LLM, so the same request can return different suggestions on different calls.

Response time is dominated by the LLM call and is typically in the order of seconds. Clients should use a generous timeout. The DataGEMS ingress allows up to 300 seconds.

Example¶

curl -X POST "https://datagems-dev.scayle.es/qr/api/v1/recommend-next-queries" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"current_query": "What is there to do in Verona tonight?", "context": {"user_id": "user1"}}'

Auth test¶

POST /api/v1/authtest

Validates the caller's token in the same way as the recommendation endpoint (signature, issuer, expiry and audience) and echoes back the request and the identity found in the token. It is useful to check a token, or a client's authentication setup, without involving the LLM.

The request body has the same shape as the auth test endpoints of the other DataGEMS Apis. Both fields are required and no other fields are allowed:

{
  "query": "test",
  "k": 1
}

Response:

{
  "authorized": true,
  "message": "Token is valid",
  "request": { "query": "test", "k": 1 },
  "subject": "the subject id",
  "username": "the preferred username"
}

Api root¶

GET /api/v1

Does not require authentication. Returns a short status message and the list of available endpoints:

{
  "message": "API V1 is running",
  "endpoints": {
    "recommend-next-queries": {
      "description": "Get the next queries given the previous one",
      "methods": ["POST"],
      "url": "/api/v1/recommend-next-queries",
      "example_url": "/api/v1/recommend-next-queries"
    },
    "authtest": {
      "description": "Test endpoint requiring a valid bearer token",
      "methods": ["POST"],
      "url": "/api/v1/authtest"
    }
  }
}

Versioning¶

The Api version is part of the path (/api/v1). Breaking changes to the request or response format will be introduced under a new path prefix.