Model Management

note

At the moment of writing this documentation, the TANGO Private API server to make the requests is hosted at this link.

Once a Deployment is configured, you can register a TANGO Model and delete it using the private API's. The registration makes a specific, prepared model available for invocation within the TANGO platform. This document details the API endpoints available for managing models.

The retrieval and invocations of the registered models is described in the Use TANGO section, in the List TANGO Models and Query TANGO Models documents.

Add a New Model

POST /api/model

important

The combination of model_code and version serves as a unique identifier across all workspaces. Once a model with a specific model_code and version is added, it cannot be added again, even after being deleted (soft delete).

Creates a new TANGO Model by providing its complete metadata. This endpoint registers a specific model version from your artifact repository with the TANGO platform, linking it to a workspace. The optional explainers associated with the model need to be registered together the model, in the dedicated explainer field in the body. At the moment, it is not possible to register and link an explainer to a model after the model has been registered. Moreover, it is also not possible to delete the model and then register it again with the explainer field due to the note above. An explainer can have in turn another explainer associated with it, creating a chain of explainers.

note

The number of supported explainers is limited to 10.

• Requires bearer token authentication (bearerAuth).

Request Body

The body must be a ModelPayload object, which defines the model's properties, its input/output schemas, and its operational requirements.

Attributes

Name	Type	Required	Description
model_code	string	Yes	A unique, alphanumeric identifier for the model.
version	string	Yes	The specific version of the model.
name	string	Yes	A human-readable name for the model.
description	string	Yes	A description of the model's purpose.
input_schema	object	Yes	The schema of the model's expected input data.
output_schema	object	Yes	The schema of the model's output data.
realtime_execution	boolean	No	Indicates if the model supports real-time execution.
allow_download	boolean	No	Indicates if the model's artifacts can be downloaded.
need_context	boolean	No	Indicates if the model requires session context for execution.
explainer	object	No	The contents is another model, with all the previous fields.

note

The workspace is automatically set to the workspace associated with the authenticated user's token.

Defining the Input and Output Schemas

The input_schema and output_schema are mandatory JSON objects that define the precise contract for data (both input and output) your model need. They are the single source of truth that tells all users and services:

1. what data your model expects;
2. in what format that data must be provided;
3. what data your model will return;
4. in what format that data will be returned.

A well-defined schema is essential for automated validation, clear user-facing documentation, and ensuring that models can be reliably integrated into the platform.

Both input_schema and output_schema follow the exact same structural rules. The following sections detail this structure, which is based on a primary type key.

Top-Level Structure

The schema object is built around the key: type. This key acts as a discriminator that determines the entire structure of the schema.

It must be one of two string values:

• "json": Use this when your model accepts (input) or returns (output) a direct JSON payload. This is for simple, structured data.
• "file": Use this when your model accepts (input) or returns (output) a file that is handled via the platform's storage, such as a CSV, image, or ZIP archive.

Based on the type you select, a different set of keys will be required to describe the data contract, as detailed in the following sections.

Schema Type: "json"

This is the simplest input/output type. Use it when the user can send, or will receive, all the required data directly in the body of the API call. The suggested schema for this type of models comprehends the following fields:

• type (string): Must be the string "json".
• description (string): A clear, human-readable description of what the data represents (e.g., "A JSON object containing applicant and loan details.").
• schema (object): An object that defines the exact structure, data types, and validation rules for the JSON payload. This object should follow the JSON Schema standard to describe the payload's type: "object", its properties, and which fields are required.

Example: json Input Schema

{
  "input_schema": {
    "type": "json",
    "description": "A JSON object containing applicant and loan details for credit risk assessment.",
    "schema": {
      "type": "object",
      "required": [
        "applicantId",
        "loanAmount",
        "monthlyIncome"
      ],
      "properties": {
        "applicantId": {
          "type": "string",
          "description": "The unique identifier for the applicant."
        },
        "loanAmount": {
          "type": "number",
          "description": "The requested loan amount in EUR."
        },
        "monthlyIncome": {
          "type": "number",
          "description": "Applicant's gross monthly income."
        }
      }
    }
  }
}

Example: json Output Schema

{
  "output_schema": {
    "type": "json",
    "description": "Returns a JSON object with the prediction result.",
    "schema": {
      "type": "object",
      "required": [
        "riskScore",
        "isApproved"
      ],
      "properties": {
        "riskScore": {
          "type": "number",
          "description": "The calculated risk score from 0.0 to 1.0."
        },
        "isApproved": {
          "type": "boolean",
          "description": "True if the loan is approved, false otherwise."
        }
      }
    }
  }
}

Schema Type: "file"

This type is required for any model that processes a file as input or produces a file as output. This workflow separates the file-handling logic from the model invocation.

• For an Input Schema: The user must first upload their file to the platform's storage to receive a fileId. If the model generates a file as output, the user must also specify an outputStorageId where the resulting file will be saved. The fileId and optionally the outputStorageId are then sent as the JSON payload to invoke the model.
• For an Output Schema: This describes the file(s) that the model will generate and save to the user-specified storage location.

Key Definitions

The suggested schema for this type of models comprehends the following fields:

• type (string): Must be the string "file".
• description (string): A human-readable description of the entire workflow (e.g., "Upload a CSV to get a fileId...").
• schema (object): An object defining the JSON payload required to invoke the model (for input) or the JSON payload returned after invocation (for output).
  • For input, this payload does not contain the file, only the pointers to it (e.g., fileId, outputStorageId).
  • For output, this payload defines the structure of the generated file.
• fileConstraints (object): An object defining the validation rules for the file's container. This is for validation before upload or after creation.
  • mediaTypes: An array of allowed file MIME types (e.g., ["text/csv"], ["image/jpeg", "image/png"]).
  • maxSizeMb: A number specifying the maximum allowed file size in megabytes.
• contentSchema (object): An object defining the rules for the file's internal content.
  • format: A string discriminator (e.g., "csv", "image", "zip") that defines how to interpret the rest of the keys in this object.
  • (other keys...): Format-specific keys (like requiredColumns for CSVs or manifest for ZIPs) that describe the internal structure.

Example: file Input Schema (CSV)

This model expects a CSV file to be uploaded. The user invokes the model by sending the file's ID and an output location ID.

"input_schema": {
  "type": "file",
  "description": "Processes a CSV file containing user transaction data. Upload the file to get a 'fileId' and specify an 'outputStorageId'.",
  "schema": {
    "type": "object",
    "required": ["fileId", "outputStorageId"],
    "properties": {
      "fileId": {
        "type": "string",
        "description": "ID of the uploaded CSV file."
      },
      "outputStorageId": {
        "type": "string",
        "description": "ID of the output storage location."
      }
    }
  },
  "fileConstraints": {
    "mediaTypes": ["text/csv"],
    "maxSizeMb": 25,
    "description": "Must be a UTF-8 encoded CSV file."
  },
  "contentSchema": {
    "format": "csv",
    "delimiter": ",",
    "requiredColumns": [
      "transaction_id",
      "date",
      "amount"
    ],
    "optionalColumns": ["merchant", "notes"],
    "notes": "Dates must be in YYYY-MM-DD format."
  }
}

Example: file Input Schema (ZIP)

This example defines a model that expects a ZIP archive containing exactly one JPEG image and one JSON metadata file.

"input_schema": {
  "type": "file",
  "description": "Processes a ZIP archive containing a main image and a JSON metadata file. Upload the file to get a 'fileId' and specify an 'outputStorageId'.",
  "schema": {
    "type": "object",
    "required": ["fileId", "outputStorageId"],
    "properties": {
      "fileId": {
        "type": "string",
        "description": "ID of the uploaded ZIP file."
      },
      "outputStorageId": {
        "type": "string",
        "description": "ID of the output storage location for the results."
      }
    }
  },
  "fileConstraints": {
    "mediaTypes": ["application/zip"],
    "maxSizeMb": 100
  },
  "contentSchema": {
    "format": "zip",
    "notes": "The ZIP archive must not be password-protected.",
    "manifest": [
      {
        "path": "image.jpg",
        "required": true,
        "description": "The primary JPEG image for processing."
      },
      {
        "path": "metadata.json",
        "required": true,
        "description": "A JSON file containing the 'author' and 'date' keys."
      }
    ]
  }
}

Example: file Output Schema (ZIP)

This model returns a ZIP archive containing multiple output files. The API call itself returns a JSON response confirming the output file's ID.

"output_schema": {
  "type": "file",
  "description": "Returns a ZIP archive containing the extracted JSON data and a marked-up image.",
  "schema": {
    "type": "object",
    "required": ["status"],
    "properties": {
      "status": {
        "type": "string",
        "description": "Status of the model execution, e.g., 'success'."
      }
    }
  },
  "fileConstraints": {
    "mediaTypes": ["application/zip"],
    "maxSizeMb": 50
  },
  "contentSchema": {
    "format": "zip",
    "notes": "The archive contains all model outputs.",
    "manifest": [
      {
        "path": "extracted_data.json",
        "required": true,
        "description": "A JSON file containing all extracted fields."
      },
      {
        "path": "annotated_image.png",
        "required": false,
        "description": "The original image with bounding boxes."
      }
    ]
  }
}

Example: Model Payload

The input_schema and output_schema are left empty to keep the example concise and readable. In a real model definition they must be specified as shown above, since they describe the structure of the data expected and returned by the model.

{
  "model_code": "customer-churn-predictor",
  "name": "Customer Churn Predictor",
  "description": "Predicts the likelihood of a customer churning.",
  "version": "3",
  "realtime_execution": true,
  "allow_download": false,
  "need_context": false,
  "input_schema": {},
  "output_schema": {},  
  "explainer": {
    "model_code": "customer-churn-explainer",
    "name": "Customer Churn Explainer",
    "description": "Explains the predictions made by the Customer Churn Predictor.",
    "version": "2",
    "realtime_execution": false,
    "allow_download": true,
    "need_context": false,
    "input_schema": {},
    "output_schema": {}
  }
}

Response Format

If successful, it returns the created Model object in an array.

---

Delete a Specific Model Version

DELETE /api/model/{modelCode}/version/{modelVersion}

Deletes a specific version of a TANGO Model.

important

This is a soft delete. It makes the model version unavailable for any new invocations or sessions, but the model_code and version combination cannot be reused. To use the same model again, you must register it with a new version.

• Requires bearer token authentication (bearerAuth).

Path Parameters

Name	Type	Required	Description	Example
modelCode	string	Yes	The unique code identifying the model.	customer-churn-predictor
modelVersion	string	Yes	The version of the model to delete.	2

Response Format

A successful 204 No Content response will be returned with a confirmation message in the body.

{
  "message": "The TANGO Model has been deleted",
  "message_code": "ok"
}