Sessions and Invocations

In the TANGO Platform, a session is a container for multiple invocations related to a specific model and user.

• A session is created for a particular model and version, and is associated with a user. It groups together all the interactions (invocations) with that model for that user.
• An invocation represents:
  • a single request to the model within a session, such as making a prediction or asking for an explanation;
  • a feedback provided by the user about a previous invocation, such as rating a prediction or providing additional context.

You must first create a session for a model, and then you can perform one or more invocations within that session. Each invocation belongs to a session and contains details about the request, its status, and the response.

To create a session, you need to specify the model code and version. The list of available models can be retrieved using the List TANGO Models endpoint.

note

At the moment of writing this documentation, the TANGO Public API server to make the requests is hosted at https://public.tango.u-hopper.com.

List Sessions

GET /api/model/{modelCode}/version/{modelVersion}/session

Retrieves a list of all TANGO Sessions for a specific TANGO Model (identified by modelCode and modelVersion).

Only sessions created by the authenticated user will be returned.

• Requires bearer token authentication (bearerAuth).

Path Parameters

Name	Type	Required	Description	Example
modelCode	string	Yes	The unique code identifying the model.	proto_model
modelVersion	string	Yes	The version of the model.	1

Response Format

[
    {
        "id": "1",
        "user_id": "1",
        "model_key": {
            "model_code": "proto_model",
            "model_version": "1"
        },
        "workspace": "default_workspace",
        "state": "OPEN"
    }
]

List TANGO Model Invocations

GET /api/model/{modelCode}/version/{modelVersion}/session/{sessionId}/invocation

Retrieves a list of all Invocations for a specific TANGO Session (identified by sessionId) of a given TANGO Model (identified by modelCode and modelVersion).

This endpoint allows users to view all invocations associated with a session, including their status and details.

Only invocations created by the authenticated user will be returned.

• Requires bearer token authentication (bearerAuth).

Path Parameters

Name	Type	Required	Description	Example
modelCode	string	Yes	The unique code identifying the model.	proto_model
modelVersion	string	Yes	The version of the model.	1
sessionId	string	Yes	The identifier of the session.	1

Response Format

[
    {
        "id": "1",
        "order": 0,
        "type": "PREDICT",
        "request": {
            "session_id": "1",
            "request_type": "FEATURES",
            "body": "{'invocation_request_key': 'invocation_request_value'}"
        },
        "status": "QUEUED",
        "response": "",
        "model_key": "",
        "related_to": null
    }
]

Notes

• The method will return an error if the session does not exist for the specified model code and version for the authenticated user.
• The status of the invocation can be one of the following: QUEUED, IN_PROGRESS, COMPLETED or ERROR.
• The response field will contain the output only when the invocation status is COMPLETED. If the invocation is still in progress or has failed, the response field will be empty.
• The related_to field is used to indicate if the invocation is related to another invocation (e.g., feedback or explanation). It will be null for regular predictions or requests.

Start a new Session

POST /api/model/{modelCode}/version/{modelVersion}/session

Creates a new TANGO Session for a specific TANGO Model (identified by modelCode and modelVersion).

This endpoint allows users to initiate a session for a model, which can then be used for invoking the model with specific inputs.

A TANGO Session for a certain model is a container for the model invocations. Each session is associated with a specific user and model and can have multiple invocations.

• Requires bearer token authentication (bearerAuth).

Path Parameters

Name	Type	Required	Description	Example
modelCode	string	Yes	The unique code identifying the model.	proto_model
modelVersion	string	Yes	The version of the model.	1

Response Format

If successful, it returns the details of the newly created session. For example:

{
    "id": "1",
    "user_id": "1",
    "model_key": {
        "model_code": "proto_model",
        "model_version": "1"
    },
    "workspace": "default_workspace",
    "state": "OPEN"
}

Update State of a Session

PATCH /api/model/{modelCode}/version/{modelVersion}/session/{sessionId}

Updates the state of a specific TANGO Session for a given TANGO Model (identified by modelCode and modelVersion).

This endpoint allows to update the state of an existing TANGO session to either OPEN or CLOSED.

• Requires bearer token authentication (bearerAuth).

Path Parameters

Name	Type	Required	Description	Example
modelCode	string	Yes	The unique code identifying the model.	proto_model
modelVersion	string	Yes	The version of the model.	1
sessionId	string	Yes	The identifier of the session.	1

Query Parameters

Name	Type	Required	Description	Allowed Values	Example
state	string	Yes	The new state of the session.	OPEN, CLOSED	CLOSED

Notes

• Only sessions considered CLOSED could be part of training datasets.
• This operation only updates the state of the session. It does not create or delete the session or affect any invocations associated with it.
• A session must exist for the specified model code and version; otherwise, an appropriate error will be returned.

Get Invocation Details

GET /api/model/{modelCode}/version/{modelVersion}/session/{sessionId}/invocation/{invocationId}

Retrieves the details of a specific Invocation (identified by invocationId) within a given TANGO Session (identified by sessionId) of a specific TANGO Model (identified by modelCode and modelVersion).

This endpoint allows users to view the details of a specific invocation, including its status, request and response.

• Requires bearer token authentication (bearerAuth).

Path Parameters

Name	Type	Required	Description	Example
modelCode	string	Yes	The unique code identifying the model.	proto_model
modelVersion	string	Yes	The version of the model.	1
sessionId	string	Yes	The identifier of the session.	1
invocationId	string	Yes	The identifier of the invocation.	1

Response Format

{
    "id": "1",
    "order": 0,
    "type": "PREDICT",
    "request": {
        "session_id": "1",
        "request_type": "FEATURES",
        "body": "{'invocation_request_key': 'invocation_request_value'}"
    },
    "status": "QUEUED",
    "response": "",
    "model_key": "",
    "related_to": null
}

Notes

• The method will return an error if the session does not exist for the specified model code and version for the authenticated user.
• The status of the invocation can be one of the following: QUEUED, IN_PROGRESS, COMPLETED or ERROR.
• The response field will contain the output only when the invocation status is COMPLETED. If the invocation is still in progress or has failed, the response field will be empty.
• If you simply need to check the status of an invocation, you can use the following endpoint instead.

Check Invocation Status

GET /api/model/{modelCode}/version/{modelVersion}/session/{sessionId}/invocation/{invocationId}/check_progress

Retrieves the status of a specific Invocation (identified by invocationId) within a given TANGO Session (identified by sessionId) of a specific TANGO Model (identified by modelCode and modelVersion).

This endpoint allows users to check the current status of an invocation without retrieving all its details.

• Requires bearer token authentication (bearerAuth).

Path Parameters

Name	Type	Required	Description	Example
modelCode	string	Yes	The unique code identifying the model.	proto_model
modelVersion	string	Yes	The version of the model.	1
sessionId	string	Yes	The identifier of the session.	1
invocationId	string	Yes	The identifier of the invocation.	1

Response Format

{
    "status": "QUEUED"
}

Notes

• The method will return an error if the session does not exist for the specified model code and version for the authenticated user.
• The status of the invocation can be one of the following: QUEUED, IN_PROGRESS, COMPLETED or ERROR.

Create a Feedback Invocation

POST /api/model/{modelCode}/version/{modelVersion}/session/{sessionId}/invocation/{invocationId}/feedback

Creates a feedback invocation for a specific TANGO Invocation (identified by invocationId) within a given TANGO Session (identified by sessionId) of a specific TANGO Model (identified by modelCode and modelVersion).

This endpoint allows users to provide feedback on a previous invocation, such as rating a prediction or providing additional context.

• Requires bearer token authentication (bearerAuth).

Path Parameters

Name	Type	Required	Description	Example
modelCode	string	Yes	The unique code identifying the model.	proto_model
modelVersion	string	Yes	The version of the model.	1
sessionId	string	Yes	The identifier of the session.	1
invocationId	string	Yes	The identifier of the invocation.	1

Request Body

The body of the request should contain data defining the feedback to be provided. The input parameters are:

• request: An object containing information about the feedback request. The request object should include:
  • body: A string containing the feedback data.

Examples Request Body

{
    "request": {
        "body": "This prediction was accurate and helpful."
    }
}

{
  "request": {
    "body": "{'rating': 5, 'comments': 'The prediction was accurate and very helpful.'}"
  }
}

Response Format

If successful, it returns the details of the newly created feedback invocation. For example:

{
    "id": "2",
    "order": 1,
    "type": "DATA_SUBMISSION",
    "request": {
        "session_id": "1",
        "request_type": "FEEDBACK",
        "body": "This prediction was accurate and helpful."
    },
    "status": "COMPLETED",
    "response": "",
    "model_key": "",
    "related_to": "1"
}