API SeveUp

Démarrer

1. 1.Créer une clé

   Dans SeveUp App, console d'organisation, section « Clés d'API » (réservée aux administrateurs) : « Clé de l'API publique », cochez les scopes utiles (projects:read, models:read, models:write, ids:read, ids:write). Le secret sk_… n'est montré qu'une fois. La même section affiche l'usage de l'API : appels, quotas du mois et erreurs.

   Copier

   export SEVEUP_API=https://api.seve-up.app
   export SEVEUP_KEY=sk_…   # clé d'organisation

2. 2.Lister les projets

   Réponse paginée par curseur : data, has_more, next_cursor.

   Copier

   curl -s "$SEVEUP_API/api/v1/projects" -H "Authorization: Bearer $SEVEUP_KEY" | jq '.data[] | {id, name}'

3. 3.Ouvrir un dépôt

   Le fichier ne passe pas par l'API : la réponse donne une adresse d'envoi TUS et ses en-têtes, valables 2 h. Idempotency-Key permet de rejouer l'appel sans créer un second dépôt.

   Copier

   FICHIER=maquette.ifc
   TAILLE=$(wc -c < "$FICHIER")
   curl -s -X POST "$SEVEUP_API/api/v1/uploads" \
     -H "Authorization: Bearer $SEVEUP_KEY" -H "Content-Type: application/json" \
     -H "Idempotency-Key: depot-$(date +%s)" \
     -d "{\"file_name\": \"$FICHIER\", \"size_bytes\": $TAILLE, \"purpose\": \"model\"}" > depot.json
   DEPOT=$(jq -r .id depot.json)

4. 4.Envoyer le fichier

   Protocole TUS 1.0 : création, puis envoi des octets. Pour un gros fichier, préférez un client TUS (tus-js-client, tuspy…) qui reprend après une coupure, avec des morceaux de 6 Mo. Puis complete vérifie que le fichier est arrivé en entier.

   Copier

   URL=$(jq -r .upload_url depot.json)
   AUTH=$(jq -r '.upload_headers.Authorization' depot.json)
   META=$(jq -r '.upload_headers["Upload-Metadata"]' depot.json)
   LOC=$(curl -s -i -X POST "$URL" -H "Authorization: $AUTH" -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Metadata: $META" -H "Upload-Length: $TAILLE" \
     | awk 'tolower($1)=="location:" {print $2}' | tr -d '\r')
   curl -s -X PATCH "$LOC" -H "Authorization: $AUTH" -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Offset: 0" -H "Content-Type: application/offset+octet-stream" --data-binary @"$FICHIER"
   curl -s -X POST "$SEVEUP_API/api/v1/uploads/$DEPOT/complete" \
     -H "Authorization: Bearer $SEVEUP_KEY" -H "Content-Type: application/json" -d '{}'

5. 5.Créer la maquette

   La conversion démarre aussitôt : réponse 202 avec un job, et son adresse dans Location. Pour une nouvelle version d'une maquette existante : POST /api/v1/models/{model_id}/revisions.

   Copier

   PROJET=…   # id d'un projet de l'étape 2
   curl -s -X POST "$SEVEUP_API/api/v1/projects/$PROJET/models" \
     -H "Authorization: Bearer $SEVEUP_KEY" -H "Content-Type: application/json" \
     -d "{\"name\": \"Ma maquette\", \"upload_id\": \"$DEPOT\"}" > job.json
   REVISION=$(jq -r .target.id job.json)

6. 6.Suivre le traitement

   Statuts : QUEUED, PROCESSING, puis COMPLETE ou ERROR (avec error.code). Plutôt que d'interroger, un webhook revision.processing.completed peut vous prévenir.

   Copier

   JOB=$(jq -r .id job.json)
   until s=$(curl -s "$SEVEUP_API/api/v1/jobs/$JOB" -H "Authorization: Bearer $SEVEUP_KEY" | jq -r .status); \
     [ "$s" = COMPLETE ] || [ "$s" = ERROR ]; do sleep 20; done; echo "$s"

7. 7.Contrôler avec un IDS et lire le résultat

   Choisissez un jeu d'exigences existant, ou déposez un .ids (dépôt purpose: ids, puis POST /api/v1/requirement-sets). Le contrôle est un job comme les autres. Dans le résultat, une spécification compte dans le score si applicable est vrai.

   Copier

   JEU=$(curl -s "$SEVEUP_API/api/v1/requirement-sets" -H "Authorization: Bearer $SEVEUP_KEY" | jq -r '.data[0].id')
   curl -s -X POST "$SEVEUP_API/api/v1/ids-checks" \
     -H "Authorization: Bearer $SEVEUP_KEY" -H "Content-Type: application/json" \
     -d "{\"revision_id\": \"$REVISION\", \"requirement_set_id\": \"$JEU\"}"
   # … suivre le job comme à l'étape 6, puis :
   curl -s "$SEVEUP_API/api/v1/revisions/$REVISION/ids-results" -H "Authorization: Bearer $SEVEUP_KEY" \
     | jq '.data[] | {score_percent, specification_count_failed}'

Erreurs

{
  "type": "https://seve-up.com/problems/validation",
  "title": "Bad Request",
  "status": 400,
  "code": "VALIDATION",
  "detail": "limit : doit être compris entre 1 et 200.",
  "instance": "/api/v1/projects",
  "errors": [
    {
      "field": "limit",
      "message": "doit être compris entre 1 et 200"
    }
  ]
}

Événements webhook

Événements envoyés en POST à l'URL d'un abonnement.

• revision.processing.completedUne révision est entièrement traitée
• revision.processing.failedLe traitement d'une révision a échoué
• ids_check.completedUn contrôle IDS est terminé
• ids_check.failedUn contrôle IDS a échoué
• export.readyUn export est prêt à télécharger

Schémas

Objets échangés par l'API, champ par champ.

• Problem
• Page
• ProcessingStatus
• Organization
• Project
• ModelUpdate
• RevisionUpdate
• ProjectCreate
• ProjectUpdate
• Model
• ModelProject
• ModelSearchItem
• ModelCreate
• StepStatus
• Revision
• RevisionCreate
• IdsSpecificationResult
• IdsResult
• IdsFacet
• IdsObjectCheck
• IdsInvalidObject
• IdsSpecificationFailure
• IdsFailures
• IdsFailuresBcf
• ObjectRow
• ObjectPage
• IdsSummary
• RequirementSet
• RequirementSetSpecification
• RequirementSetSpecifications
• RequirementSetCreate
• Space
• DashboardTemplate
• Dashboard
• DashboardCreate
• SpaceRequirementSet
• IdsCheckCreate
• ExportCreate
• UploadCreate
• Upload
• Job
• NamingConvention
• NamingConventionPart
• NamingProblem
• FileNameCheckRequest
• FileNameResult
• FileNameCheck
• ModelNameCheck
• VisaGrid
• DocumentVersion
• Document
• DocumentDownload
• KairnialProject
• KairnialExportCreate
• KairnialExport
• VisaSheet
• IssueBoard
• IssueComment
• Issue
• IssueCreate
• IssueUpdate
• IssueCommentCreate
• WebhookEventType
• Webhook
• WebhookCreate
• WebhookDelivery
• WebhookEvent

Versions et dépréciation

• La version majeure est dans le chemin : /api/v1. À l'intérieur d'une version, seuls des changements compatibles sont publiés : nouvelles opérations, nouveaux champs de réponse, nouveaux paramètres facultatifs. Votre code doit ignorer les champs qu'il ne connaît pas et traiter un code d'erreur inconnu d'après le statut HTTP : la liste des codes peut s'allonger.

• Un changement incompatible (champ retiré ou renommé, type modifié, paramètre rendu obligatoire) passe par une nouvelle version, /api/v2. La version précédente reste servie au moins 12 mois après la sortie de la suivante.

• Dans v1, un champ n'est jamais retiré. Une opération vouée à disparaître est annoncée au moins 6 mois avant son retrait : entrée dans le journal des changements (aussi en flux Atom), e-mail aux administrateurs des organisations dont une clé l'a appelée dans les 90 derniers jours, 6 mois puis 1 mois avant le retrait, et en-têtes Deprecation (RFC 9745), Sunset (RFC 8594) et Link (rel="deprecation", vers le journal) sur ses réponses. Elle fonctionne normalement jusqu'à la date de retrait, puis répond 410 avec le code GONE.

• Seule exception : un correctif de sécurité peut s'appliquer sans préavis. Il est alors décrit dans le journal des changements le jour même.

Journal des changements

Journal complet, changement par changementVersion JSONFlux AtomToute la référence en Markdown (pour les agents IA)

1. 2026-11-13 · v1.18.0

   Nouvelle opération : GET /api/v1/organization.

2. 2026-11-12 · v1.17.0

   Nouvelle opération : GET /api/v1/models.

3. 2026-11-12 · v1.16.0

   Nouvelle opération : GET /api/v1/dashboard-templates, GET /api/v1/spaces, GET /api/v1/spaces/{space_id}/dashboards, POST /api/v1/spaces/{space_id}/dashboards, POST /api/v1/spaces/{space_id}/requirement-sets ; Nouveau paramètre facultatif : GET /api/v1/requirement-sets ; Nouveau champ facultatif dans la requête : POST /api/v1/requirement-sets ; Nouveau statut d'erreur documenté : POST /api/v1/requirement-sets.

4. 2026-11-10 · v1.15.0

   Nouveau champ de réponse : GET /api/v1/revisions/{revision_id}/ids-results.

5. 2026-11-09 · v1.14.0

   Nouveau paramètre facultatif : GET /api/v1/revisions/{revision_id}/objects ; Nouveau champ de réponse : GET /api/v1/revisions/{revision_id}/objects.