API de gestion

Usage

Les endpoints de gestion permettent a une integration de configurer des objets Kitemesh via l’API publique: secrets, outils, ressources API, fichiers, modeles personnalises et groupes de modeles.

Utilisez-les uniquement avec des tokens API qui doivent modifier la configuration. Gardez ces capacites desactivees pour les integrations limitees au chat.

Authentification et capacites

Tous les endpoints demandent:

Authorization: Bearer km_your_token_here

Le token doit appartenir a l’equipe ou les objets sont geres. Il doit aussi avoir la capacite correspondante:

Ressource	Capacite requise
Secrets	manageSecrets
Outils	manageTools
Ressources API	manageResources
Fichiers	uploadFiles pour le televersement; acces a la ressource pour lire et supprimer
Modeles personnalises	manageCustomModels
Groupes de modeles	manageGroups

Les portees de partage doivent aussi etre autorisees par la politique du token. Une portee de partage a cette forme:

{
  "type": "team",
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Les valeurs acceptees pour type sont team, customModel et groupModel.

Endpoints de liste

Les endpoints de liste renvoient les objets visibles par le token. Les champs de pagination dependent de la famille de ressource.

Endpoint	Champs de requete utiles
GET /v1/secrets	scope, teamId, q, limit, cursor
GET /v1/tools	scopeType, scopeId, page, pageSize
GET /v1/api-resources	scopeType, scopeId, page, pageSize
GET /v1/files	scopeType, scopeId, resourceType, status, search, page, pageSize
GET /v1/custom-models	scope, teamId, search, category, tags, sort, credentialMode, limit, cursor
GET /v1/group-models	scope, teamId, search, category, tags, sort, mode, limit, cursor

Limites courantes:

• limit: 1 a 100 sur les secrets et listes de modeles
• pageSize: 1 a 100 sur les outils, ressources API et fichiers
• scope: mine, team, public ou all sur les listes de modeles
• sort: updated, created, name ou author sur les listes de modeles

Secrets

Les secrets stockent des valeurs sensibles utilisees par les outils et les modeles personnalises BYOK. Une valeur de secret peut etre ecrite ou remplacee, mais un client ne doit pas attendre des reponses de liste ou de lecture qu’elles revelent la valeur.

Methode et chemin	Usage
POST /v1/secrets	creer un secret
GET /v1/secrets	lister les secrets visibles
PATCH /v1/secrets/:id	mettre a jour les metadonnees ou remplacer la valeur
DELETE /v1/secrets/:id	supprimer un secret

Champs de creation:

Champ	Type	Obligatoire	Notes
name	string	oui	1 a 160 caracteres
description	string	non	jusqu’a 2000 caracteres
provider	string	non	jusqu’a 80 caracteres
scope	string	oui	user ou team
teamId	string	non	UUID; requis pour un secret d’equipe
value	string	oui	valeur secrete

La mise a jour accepte name, description, provider et value.

curl -X POST "https://your-kitemesh.example.com/v1/secrets" \
  -H "Authorization: Bearer km_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer API key",
    "provider": "customer-api",
    "scope": "team",
    "teamId": "123e4567-e89b-12d3-a456-426614174000",
    "value": "secret_value_here"
  }'

Outils

Les outils sont des actions HTTP. Utilisez-les pour les operations qui creent, mettent a jour ou suppriment des donnees, ou pour les lectures qui demandent des controles d’approbation.

Methode et chemin	Usage
POST /v1/tools	creer un outil
GET /v1/tools	lister les outils visibles
GET /v1/tools/:id	lire un outil
PATCH /v1/tools/:id	mettre a jour un outil
DELETE /v1/tools/:id	supprimer un outil

Champs de creation:

Champ	Type	Obligatoire	Notes
name	string	oui	1 a 120 caracteres
description	string	oui	1 a 4000 caracteres
method	string	oui	POST, PATCH, PUT ou DELETE
needUserValidation	boolean	non	vaut true par defaut si absent
argsSchema	object	non	objet de type schema JSON pour les arguments
urlTemplate	string	oui	modele d’URL cible
staticHeadersNonSecret	object	non	en-tetes non secrets uniquement
timeoutMs	integer	non	0 a 120000
authFields	array	non	entrees avec key et secretId
scopes	array	non	portees de partage
tags	array<string>	non	libelles de tags
version	string	non	libelle de version defini par le client

La mise a jour accepte les champs modifiables de l’outil. method, scopes, tags et version sont des champs de creation dans le contrat public.

curl -X POST "https://your-kitemesh.example.com/v1/tools" \
  -H "Authorization: Bearer km_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Create support ticket",
    "description": "Creates a support ticket for the current customer.",
    "method": "POST",
    "needUserValidation": true,
    "urlTemplate": "https://api.example.com/tickets",
    "argsSchema": {
      "type": "object",
      "properties": {
        "priority": { "type": "string" },
        "summary": { "type": "string" }
      },
      "required": ["summary"]
    },
    "authFields": [
      {
        "key": "Authorization",
        "secretId": "123e4567-e89b-12d3-a456-426614174222"
      }
    ],
    "scopes": [
      {
        "type": "groupModel",
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }'

Ressources API

Les ressources API exposent un contexte HTTP en lecture seule. Ce sont des ressources GET, separees des outils d’action.

Methode et chemin	Usage
POST /v1/api-resources	creer une ressource API
GET /v1/api-resources	lister les ressources API visibles
GET /v1/api-resources/:id	lire une ressource API
PATCH /v1/api-resources/:id	mettre a jour une ressource API
DELETE /v1/api-resources/:id	supprimer une ressource API

Champs de creation:

Champ	Type	Obligatoire	Notes
name	string	oui	1 a 120 caracteres
description	string	oui	1 a 4000 caracteres
urlTemplate	string	oui	modele d’URL GET
staticHeadersNonSecret	object	non	en-tetes non secrets uniquement
timeoutMs	integer	non	0 a 120000
cacheTtlSeconds	integer	non	0 ou plus
scopes	array	non	portees de partage

La mise a jour accepte name, description, urlTemplate, staticHeadersNonSecret, timeoutMs et cacheTtlSeconds.

Fichiers

Les fichiers sont televerses en multipart form data. Le formulaire doit contenir une partie file et un champ metadata contenant du JSON.

Methode et chemin	Usage
POST /v1/files	televerser un fichier
GET /v1/files	lister les fichiers visibles
GET /v1/files/vectorization-status	lire le statut de traitement d’un ou plusieurs fichiers
GET /v1/files/:id	lire une ressource fichier
DELETE /v1/files/:id	supprimer une ressource fichier

Champs de metadata:

Champ	Type	Obligatoire	Notes
resourceType	string	oui	text, image, audio ou video
scope	string	non	user ou conversation
conversationId	string	non	UUID pour un televersement rattache a une conversation
scopes	array	non	portees de partage
fileName	string	non	jusqu’a 255 caracteres

La limite de televersement par defaut est de 5 Mo. Le champ metadata est limite a 64 Ko par defaut.

curl -X POST "https://your-kitemesh.example.com/v1/files" \
  -H "Authorization: Bearer km_your_token_here" \
  -F "file=@./brief.pdf" \
  -F 'metadata={
    "resourceType": "text",
    "scope": "user",
    "fileName": "brief.pdf",
    "scopes": [
      {
        "type": "groupModel",
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }'

GET /v1/files/vectorization-status accepte ids sous forme de parametre separe par des virgules ou de parametre repete:

GET /v1/files/vectorization-status?ids=123e4567-e89b-12d3-a456-426614174000,123e4567-e89b-12d3-a456-426614174111

Les statuts de fichier incluent pending, vectorizing, ready, failed et deleting.

Modeles personnalises

Les modeles personnalises enveloppent un LLM avec des instructions reutilisables, une visibilite et des reglages d’identifiants.

Methode et chemin	Usage
POST /v1/custom-models	creer un modele personnalise
GET /v1/custom-models	lister les modeles personnalises visibles
GET /v1/custom-models/:id	lire un modele personnalise
PATCH /v1/custom-models/:id	mettre a jour un modele personnalise
DELETE /v1/custom-models/:id	supprimer un modele personnalise

Champs de creation:

Champ	Type	Obligatoire	Notes
name	string	oui	1 a 200 caracteres
llmModelName	string	oui	nom du modele
description	string	non	jusqu’a 2000 caracteres
category	string	non	jusqu’a 80 caracteres
tags	array<string>	non	chaque tag jusqu’a 64 caracteres
defaultSystemInstruction	string	non	jusqu’a 20000 caracteres
isPublic	boolean	non	indicateur de visibilite publique
teamIds	array<string>	non	UUID des equipes ayant acces
credentialMode	string	non	app ou byok
byokSecretId	string	non	UUID d’un secret du coffre fort pour BYOK

Les memes champs sont acceptes en mise a jour, tous optionnels.

Utilisez le modele cree en chat avec model: "custom:<uuid>".

Groupes de modeles

Les groupes de modeles combinent une cible brain, des agents optionnels et un mode par defaut.

Methode et chemin	Usage
POST /v1/group-models	creer un groupe de modeles
GET /v1/group-models	lister les groupes de modeles visibles
GET /v1/group-models/:id	lire un groupe de modeles
PATCH /v1/group-models/:id	mettre a jour un groupe de modeles
DELETE /v1/group-models/:id	supprimer un groupe de modeles

Champs de creation:

Champ	Type	Obligatoire	Notes
name	string	oui	1 a 200 caracteres
description	string	non	jusqu’a 2000 caracteres
category	string	non	jusqu’a 80 caracteres
tags	array<string>	non	chaque tag jusqu’a 64 caracteres
icon	string	non	nom d’icone pris en charge
defaultMode	string	oui	orch, synth, normal ou auto
brain	object	oui	reference de modele
agents	array	non	references d’agents
isPublic	boolean	non	indicateur de visibilite publique
teamIds	array<string>	non	UUID des equipes ayant acces

Les valeurs prises en charge pour icon sont account_tree, forum, travel_explore, edit_note, monitoring, gavel, school, smart_toy, support_agent, campaign, analytics et history_edu.

brain et agents[].ref utilisent des references de modele:

{
  "type": "llm",
  "llmModelName": "gpt-5-mini"
}

Les entrees d’agent peuvent aussi contenir:

Champ	Type	Notes
role	string	1 a 64 caracteres
instructionOverride	string	jusqu’a 20000 caracteres

GET /v1/group-models/:id accepte resolve=none, resolve=shallow ou resolve=deep. La resolution ajoute des details lisibles aux references de modeles quand le token y a acces.

curl -X POST "https://your-kitemesh.example.com/v1/group-models" \
  -H "Authorization: Bearer km_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research group",
    "defaultMode": "auto",
    "brain": {
      "type": "llm",
      "llmModelName": "gpt-5-mini"
    },
    "agents": [
      {
        "ref": {
          "type": "custom",
          "customModelId": "123e4567-e89b-12d3-a456-426614174111"
        },
        "role": "researcher"
      }
    ],
    "teamIds": [
      "123e4567-e89b-12d3-a456-426614174000"
    ]
  }'

Utilisez le groupe cree en chat avec model: "group:<uuid>".