Applications

Une application est une application réutilisable : un modèle, un ensemble de champs de saisie que votre appelant remplit, et les instructions envoyées au modèle. Vous créez les applications par cette ressource, puis vous les lancez par Exécutions. Une application est privée à votre projet jusqu'à ce que vous la publiiez, moment où elle apparaît également dans le Catalogue.

Les appels

<app_id> est un identifiant d'application, préfixé mapp_. La modification et la suppression agissent toutes deux sur le chemin detail ; il n'existe pas de chemin distinct pour la mise à jour ou la suppression.

L'objet application

Chaque entrée de data décrit un champ de saisie :

runs et tokens répondent à deux questions différentes : combien de fois l'application a été lancée, et ce que ces lancements ont dépensé. tokens couvre toute la vie de l'application, et non le cycle de facturation en cours, et ne compte que les exécutions de votre propre projet — lire l'application publique d'un tiers rapporte donc ce que vous y avez dépensé. Les exécutions terminées en erreur sont écartées, ce qui fait correspondre le total au chiffre affiché par l'espace de travail pour la même application. Voir Quota et consommation de tokens pour les chiffres du cycle à l'échelle du projet.

Note — tokens vaut null, et non trois zéros, lorsque les exécutions du projet ne portent aucune mesure de tokens. Une application qui existe mais n'a jamais été lancée répond 0 sur les trois champs.

Créer une application

POST /v1/app/create exige un nom, une description, au moins un champ de saisie et au moins une instruction.

curl -X POST https://api.think.ultineo.com/v1/app/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support triage",
    "description": "Sorts an inbound support message by urgency.",
    "category": "text",
    "data": [
      { "type": "input", "name": "message", "placeholder": "Paste the message", "required": true }
    ],
    "instruction": [
      { "type": "system", "instruction": "Classify the message as low, normal or urgent." }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "mapp_0ceacb46e5b3a99e91b6",
    "object": "app",
    "name": "Support triage",
    "description": "Sorts an inbound support message by urgency.",
    "category": "text",
    "model": "modi_7b1e4c2a9d05f3618ea4",
    "model_library": "mlyi_2c9a7f45b8e1d06a3427",
    "data": {
      "madi_5d8b21c74e0af96b3d15": {
        "type": "input",
        "value": "message",
        "placeholder": "Paste the message",
        "required": true
      }
    },
    "instruction": {
      "miid_9a4c07e5b312df8641ca": {
        "type": "system",
        "instruction": "Classify the message as low, normal or urgent."
      }
    },
    "status": "activated",
    "created_at": 1754205600
  }
}

Note — La création répond 200, et non 201, et ses data et instruction sont des objets indexés par les nouveaux identifiants plutôt que les tableaux que renvoient les appels de lecture. Relisez l'application avec GET /v1/app/detail/<app_id> si vous avez besoin de la forme standard.

Au moins un champ de data doit être obligatoire, sinon l'appel est refusé par un 422 et At least one data field must be required. Un type de champ inconnu donne 404 et The selected data type does not exist., et un type d'instruction inconnu donne 404 et The selected instruction type does not exist.

Types de champ de données

Le type que vous envoyez dans data est l'un des noms ci-dessous (son identifiant est également accepté, et c'est l'identifiant que renvoient les points d'accès de lecture).

Les champs document et image ne prennent pas de texte saisi : une exécution fournit un fichier déjà envoyé par votre projet. Voir Exécutions pour savoir comment en envoyer un, et notez qu'un champ image ne fonctionne qu'avec un modèle qui lit les images.

La création dépend également de l'abonnement du projet. Un abonnement qui n'autorise aucune application sur mesure, et un projet qui a atteint sa limite d'applications, sont tous deux refusés par un 402 — voir Codes d'erreur.

Lister vos applications

GET /v1/app/list renvoie les applications propres au projet, les plus récentes d'abord, en excluant celles qui ont été supprimées. Il accepte limit et offset.

curl "https://api.think.ultineo.com/v1/app/list?limit=2" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "data": [
      {
        "id": "mapp_0ceacb46e5b3a99e91b6",
        "object": "app",
        "name": "Support triage",
        "description": "Sorts an inbound support message by urgency.",
        "type": "private",
        "status": "activated",
        "model": "modi_7b1e4c2a9d05f3618ea4",
        "model_library": "mlyi_2c9a7f45b8e1d06a3427",
        "runs": { "private": 12, "public": 0 },
        "tokens": { "input": 8420, "output": 3115, "total": 11535 },
        "created_at": 1754205600,
        "updated_at": 1754205600
      }
    ],
    "total": 1
  }
}

La liste omet data, instruction et logo. Lisez une application pour les obtenir.

Consulter une application

GET /v1/app/detail/<app_id> renvoie l'objet complet, y compris le schéma de saisie dont vous avez besoin pour lancer une exécution.

curl https://api.think.ultineo.com/v1/app/detail/mapp_0ceacb46e5b3a99e91b6 \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "mapp_0ceacb46e5b3a99e91b6",
    "object": "app",
    "name": "Support triage",
    "description": "Sorts an inbound support message by urgency.",
    "type": "private",
    "status": "activated",
    "logo": "file_d81e4afa6c8bf11fa881",
    "model": "modi_7b1e4c2a9d05f3618ea4",
    "model_library": "mlyi_2c9a7f45b8e1d06a3427",
    "data": [
      {
        "id": "madi_5d8b21c74e0af96b3d15",
        "name": "message",
        "type": "mdti_c2a39a7ad82bc017dccd",
        "placeholder": "Paste the message",
        "required": true
      }
    ],
    "instruction": [
      {
        "id": "miid_9a4c07e5b312df8641ca",
        "type": "system",
        "instruction": "Classify the message as low, normal or urgent."
      }
    ],
    "runs": { "private": 12, "public": 0 },
    "tokens": { "input": 8420, "output": 3115, "total": 11535 },
    "created_at": 1754205600,
    "updated_at": 1754205600
  }
}

Vous pouvez lire vos propres applications dans n'importe quel statut, ainsi que toute application publique activée de n'importe quel projet. La lecture de l'application publique d'un tiers masque ce qui appartient à son propriétaire : instruction revient à null, runs.private à 0, et tokens rapporte ce que votre propre projet y a dépensé plutôt que le total du propriétaire. Tout autre cas donne 404 et App not found.

Modifier une application

PATCH /v1/app/detail/<app_id> change le nom, la description et la visibilité. Envoyez au moins l'un des trois.

curl -X PATCH https://api.think.ultineo.com/v1/app/detail/mapp_0ceacb46e5b3a99e91b6 \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "public" }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "mapp_0ceacb46e5b3a99e91b6",
    "object": "app",
    "name": "Support triage",
    "description": "Sorts an inbound support message by urgency.",
    "type": "public",
    "status": "activated",
    "model": "modi_7b1e4c2a9d05f3618ea4",
    "model_library": "mlyi_2c9a7f45b8e1d06a3427",
    "created_at": 1754205600,
    "updated_at": 1754209200
  }
}

La publication a deux conditions. L'application doit déjà être activée, sinon l'appel est refusé par un 422 et The app must be activated before it can be published., et elle doit porter un logo image, sinon 422 et The app needs an image logo before it can be published. Le retrait d'une application réussit toujours. Un type qui ne vaut ni l'un ni l'autre donne 422 et type must be 'public' or 'private'.

N'envoyer rien de reconnaissable donne 422 et Nothing to update. Provide name, description and/or type.

Supprimer une application

DELETE /v1/app/detail/<app_id> retire l'application. Elle cesse d'apparaître dans tous les listages et ne peut plus être ni lue ni lancée.

curl -X DELETE https://api.think.ultineo.com/v1/app/detail/mapp_0ceacb46e5b3a99e91b6 \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "deleted": true,
    "id": "mapp_0ceacb46e5b3a99e91b6"
  }
}

Note — Les exécutions que l'application a déjà produites sont conservées et restent consultables par Exécutions.