API externe

Sim fournit une API externe complète pour interroger les journaux d'exécution des workflows et configurer des webhooks pour des notifications en temps réel lorsque les workflows sont terminés.

Authentification

Toutes les requêtes API nécessitent une clé API transmise dans l'en-tête x-api-key :

curl -H "x-api-key: YOUR_API_KEY" \
  https://sim.ai/api/v1/logs?workspaceId=YOUR_WORKSPACE_ID

Vous pouvez générer des clés API depuis vos paramètres utilisateur dans le tableau de bord Sim.

API des journaux

Toutes les réponses API incluent des informations sur vos limites d'exécution de workflow et votre utilisation :

"limits": {
  "workflowExecutionRateLimit": {
    "sync": {
      "requestsPerMinute": 60,  // Sustained rate limit per minute
      "maxBurst": 120,          // Maximum burst capacity
      "remaining": 118,         // Current tokens available (up to maxBurst)
      "resetAt": "..."          // When tokens next refill
    },
    "async": {
      "requestsPerMinute": 200, // Sustained rate limit per minute
      "maxBurst": 400,          // Maximum burst capacity
      "remaining": 398,         // Current tokens available
      "resetAt": "..."          // When tokens next refill
    }
  },
  "usage": {
    "currentPeriodCost": 1.234,  // Current billing period usage in USD
    "limit": 10,                  // Usage limit in USD
    "plan": "pro",                // Current subscription plan
    "isExceeded": false           // Whether limit is exceeded
  }
}

Remarque : les limites de débit utilisent un algorithme de seau à jetons. remaining peut dépasser requestsPerMinute jusqu'à maxBurst lorsque vous n'avez pas utilisé récemment votre allocation complète, permettant ainsi un trafic en rafale. Les limites de débit dans le corps de la réponse concernent les exécutions de workflow. Les limites de débit pour appeler ce point de terminaison API se trouvent dans les en-têtes de réponse (X-RateLimit-*).

Interrogation des journaux

Interrogez les journaux d'exécution des workflows avec de nombreuses options de filtrage.

GET /api/v1/logs

{
  "data": [
    {
      "id": "log_abc123",
      "workflowId": "wf_xyz789",
      "executionId": "exec_def456",
      "level": "info",
      "trigger": "api",
      "startedAt": "2025-01-01T12:34:56.789Z",
      "endedAt": "2025-01-01T12:34:57.123Z",
      "totalDurationMs": 334,
      "cost": {
        "total": 0.00234
      },
      "files": null
    }
  ],
  "nextCursor": "eyJzIjoiMjAyNS0wMS0wMVQxMjozNDo1Ni43ODlaIiwiaWQiOiJsb2dfYWJjMTIzIn0",
  "limits": {
    "workflowExecutionRateLimit": {
      "sync": {
        "requestsPerMinute": 60,
        "maxBurst": 120,
        "remaining": 118,
        "resetAt": "2025-01-01T12:35:56.789Z"
      },
      "async": {
        "requestsPerMinute": 200,
        "maxBurst": 400,
        "remaining": 398,
        "resetAt": "2025-01-01T12:35:56.789Z"
      }
    },
    "usage": {
      "currentPeriodCost": 1.234,
      "limit": 10,
      "plan": "pro",
      "isExceeded": false
    }
  }
}

Obtenir les détails du journal

Récupérer des informations détaillées sur une entrée de journal spécifique.

GET /api/v1/logs/{id}

{
  "data": {
    "id": "log_abc123",
    "workflowId": "wf_xyz789",
    "executionId": "exec_def456",
    "level": "info",
    "trigger": "api",
    "startedAt": "2025-01-01T12:34:56.789Z",
    "endedAt": "2025-01-01T12:34:57.123Z",
    "totalDurationMs": 334,
    "workflow": {
      "id": "wf_xyz789",
      "name": "My Workflow",
      "description": "Process customer data"
    },
    "executionData": {
      "traceSpans": [...],
      "finalOutput": {...}
    },
    "cost": {
      "total": 0.00234,
      "tokens": {
        "prompt": 123,
        "completion": 456,
        "total": 579
      },
      "models": {
        "gpt-4o": {
          "input": 0.001,
          "output": 0.00134,
          "total": 0.00234,
          "tokens": {
            "prompt": 123,
            "completion": 456,
            "total": 579
          }
        }
      }
    },
    "limits": {
      "workflowExecutionRateLimit": {
        "sync": {
          "requestsPerMinute": 60,
          "maxBurst": 120,
          "remaining": 118,
          "resetAt": "2025-01-01T12:35:56.789Z"
        },
        "async": {
          "requestsPerMinute": 200,
          "maxBurst": 400,
          "remaining": 398,
          "resetAt": "2025-01-01T12:35:56.789Z"
        }
      },
      "usage": {
        "currentPeriodCost": 1.234,
        "limit": 10,
        "plan": "pro",
        "isExceeded": false
      }
    }
  }
}

Obtenir les détails d'exécution

Récupérer les détails d'exécution, y compris l'instantané de l'état du workflow.

GET /api/v1/logs/executions/{executionId}

{
  "executionId": "exec_def456",
  "workflowId": "wf_xyz789",
  "workflowState": {
    "blocks": {...},
    "edges": [...],
    "loops": {...},
    "parallels": {...}
  },
  "executionMetadata": {
    "trigger": "api",
    "startedAt": "2025-01-01T12:34:56.789Z",
    "endedAt": "2025-01-01T12:34:57.123Z",
    "totalDurationMs": 334,
    "cost": {...}
  }
}

Notifications

Recevez des notifications en temps réel lorsque les exécutions de flux de travail sont terminées via webhook, e-mail ou Slack. Les notifications sont configurées au niveau de l'espace de travail depuis la page Logs.

Configuration

Configurez les notifications depuis la page Logs en cliquant sur le bouton menu et en sélectionnant "Configurer les notifications".

Canaux de notification :

• Webhook : envoi de requêtes HTTP POST à votre point de terminaison
• E-mail : réception de notifications par e-mail avec les détails d'exécution
• Slack : publication de messages dans un canal Slack

Sélection de flux de travail :

• Sélectionnez des flux de travail spécifiques à surveiller
• Ou choisissez "Tous les flux de travail" pour inclure les flux actuels et futurs

Options de filtrage :

• levelFilter : niveaux de journalisation à recevoir (info, error)
• triggerFilter : types de déclencheurs à recevoir (api, webhook, schedule, manual, chat)

Données optionnelles :

• includeFinalOutput : inclure le résultat final du flux de travail
• includeTraceSpans : inclure les traces détaillées d'exécution
• includeRateLimits : inclure les informations de limite de débit (limites synchrones/asynchrones et restantes)
• includeUsageData : inclure l'utilisation et les limites de la période de facturation

Règles d'alerte

Au lieu de recevoir des notifications pour chaque exécution, configurez des règles d'alerte pour être notifié uniquement lorsque des problèmes sont détectés :

Échecs consécutifs

• Alerte après X exécutions échouées consécutives (par exemple, 3 échecs d'affilée)
• Réinitialisation lorsqu'une exécution réussit

Taux d'échec

• Alerte lorsque le taux d'échec dépasse X % au cours des Y dernières heures
• Nécessite un minimum de 5 exécutions dans la fenêtre
• Ne se déclenche qu'après l'écoulement complet de la fenêtre temporelle

Seuil de latence

• Alerte lorsqu'une exécution prend plus de X secondes
• Utile pour détecter les flux de travail lents ou bloqués

Pic de latence

• Alerte lorsque l'exécution est X % plus lente que la moyenne
• Compare à la durée moyenne sur la fenêtre temporelle configurée
• Nécessite un minimum de 5 exécutions pour établir une référence

Seuil de coût

• Alerte lorsqu'une seule exécution coûte plus de X €
• Utile pour détecter les appels LLM coûteux

Aucune activité

• Alerte lorsqu'aucune exécution ne se produit pendant X heures
• Utile pour surveiller les workflows programmés qui devraient s'exécuter régulièrement

Nombre d'erreurs

• Alerte lorsque le nombre d'erreurs dépasse X dans une fenêtre temporelle
• Suit le total des erreurs, pas les erreurs consécutives

Tous les types d'alertes incluent un temps de récupération d'une heure pour éviter le spam de notifications.

Configuration du webhook

Pour les webhooks, des options supplémentaires sont disponibles :

• url : l'URL de votre point de terminaison webhook
• secret : secret optionnel pour la vérification de signature HMAC

Structure de la charge utile

Lorsqu'une exécution de workflow se termine, Sim envoie la charge utile suivante (via webhook POST, e-mail ou Slack) :

{
  "id": "evt_123",
  "type": "workflow.execution.completed",
  "timestamp": 1735925767890,
  "data": {
    "workflowId": "wf_xyz789",
    "executionId": "exec_def456",
    "status": "success",
    "level": "info",
    "trigger": "api",
    "startedAt": "2025-01-01T12:34:56.789Z",
    "endedAt": "2025-01-01T12:34:57.123Z",
    "totalDurationMs": 334,
    "cost": {
      "total": 0.00234,
      "tokens": {
        "prompt": 123,
        "completion": 456,
        "total": 579
      },
      "models": {
        "gpt-4o": {
          "input": 0.001,
          "output": 0.00134,
          "total": 0.00234,
          "tokens": {
            "prompt": 123,
            "completion": 456,
            "total": 579
          }
        }
      }
    },
    "files": null,
    "finalOutput": {...},  // Only if includeFinalOutput=true
    "traceSpans": [...],   // Only if includeTraceSpans=true
    "rateLimits": {...},   // Only if includeRateLimits=true
    "usage": {...}         // Only if includeUsageData=true
  },
  "links": {
    "log": "/v1/logs/log_abc123",
    "execution": "/v1/logs/executions/exec_def456"
  }
}

En-têtes webhook

Chaque requête webhook inclut ces en-têtes (canal webhook uniquement) :

• sim-event : type d'événement (toujours workflow.execution.completed)
• sim-timestamp : horodatage Unix en millisecondes
• sim-delivery-id : ID de livraison unique pour l'idempotence
• sim-signature : signature HMAC-SHA256 pour vérification (si un secret est configuré)
• Idempotency-Key : identique à l'ID de livraison pour la détection des doublons

Vérification de signature

Si vous configurez un secret webhook, vérifiez la signature pour vous assurer que le webhook provient de Sim :

import crypto from 'crypto';

function verifyWebhookSignature(body, signature, secret) {
  const [timestampPart, signaturePart] = signature.split(',');
  const timestamp = timestampPart.replace('t=', '');
  const expectedSignature = signaturePart.replace('v1=', '');
  
  const signatureBase = `${timestamp}.${body}`;
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(signatureBase);
  const computedSignature = hmac.digest('hex');
  
  return computedSignature === expectedSignature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['sim-signature'];
  const body = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook...
});

import hmac
import hashlib
import json

def verify_webhook_signature(body: str, signature: str, secret: str) -> bool:
    timestamp_part, signature_part = signature.split(',')
    timestamp = timestamp_part.replace('t=', '')
    expected_signature = signature_part.replace('v1=', '')
    
    signature_base = f"{timestamp}.{body}"
    computed_signature = hmac.new(
        secret.encode(),
        signature_base.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(computed_signature, expected_signature)

# In your webhook handler
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('sim-signature')
    body = json.dumps(request.json)
    
    if not verify_webhook_signature(body, signature, os.environ['WEBHOOK_SECRET']):
        return 'Invalid signature', 401
    
    # Process the webhook...

Politique de nouvelle tentative

Les livraisons de webhook échouées sont réessayées avec un backoff exponentiel et du jitter :

• Nombre maximum de tentatives : 5
• Délais de nouvelle tentative : 5 secondes, 15 secondes, 1 minute, 3 minutes, 10 minutes
• Jitter : jusqu'à 10 % de délai supplémentaire pour éviter l'effet de horde
• Seules les réponses HTTP 5xx et 429 déclenchent de nouvelles tentatives
• Les livraisons expirent après 30 secondes

Bonnes pratiques

1. Stratégie de polling : Lors du polling des logs, utilisez la pagination basée sur curseur avec order=asc et startDate pour récupérer efficacement les nouveaux logs.

2. Sécurité des webhooks : Configurez toujours un secret de webhook et vérifiez les signatures pour vous assurer que les requêtes proviennent de Sim.

3. Idempotence : Utilisez l'en-tête Idempotency-Key pour détecter et gérer les livraisons de webhook en double.

4. Confidentialité : Par défaut, finalOutput et traceSpans sont exclus des réponses. Activez-les uniquement si vous avez besoin des données et comprenez les implications en matière de confidentialité.

5. Limitation de débit : Implémentez un backoff exponentiel lorsque vous recevez des réponses 429. Vérifiez l'en-tête Retry-After pour connaître le temps d'attente recommandé.

Limitation de débit

L'API utilise un algorithme de seau à jetons pour limiter le débit, offrant une utilisation équitable tout en permettant des pics de trafic :

Comment ça fonctionne :

• Les jetons se rechargent au rythme de requestsPerMinute
• Vous pouvez accumuler jusqu'à maxBurst jetons en période d'inactivité
• Chaque requête consomme 1 jeton
• La capacité de rafale permet de gérer les pics de trafic

Les informations sur les limites de débit sont incluses dans les en-têtes de réponse :

• X-RateLimit-Limit : requêtes par minute (taux de recharge)
• X-RateLimit-Remaining : jetons actuellement disponibles
• X-RateLimit-Reset : horodatage ISO indiquant quand les jetons seront rechargés

Exemple : interrogation pour de nouveaux journaux

let cursor = null;
const workspaceId = 'YOUR_WORKSPACE_ID';
const startDate = new Date().toISOString();

async function pollLogs() {
  const params = new URLSearchParams({
    workspaceId,
    startDate,
    order: 'asc',
    limit: '100'
  });
  
  if (cursor) {
    params.append('cursor', cursor);
  }
  
  const response = await fetch(
    `https://sim.ai/api/v1/logs?${params}`,
    {
      headers: {
        'x-api-key': 'YOUR_API_KEY'
      }
    }
  );
  
  if (response.ok) {
    const data = await response.json();
    
    // Process new logs
    for (const log of data.data) {
      console.log(`New execution: ${log.executionId}`);
    }
    
    // Update cursor for next poll
    if (data.nextCursor) {
      cursor = data.nextCursor;
    }
  }
}

// Poll every 30 seconds
setInterval(pollLogs, 30000);

Exemple : traitement des webhooks

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

app.post('/sim-webhook', (req, res) => {
  // Verify signature
  const signature = req.headers['sim-signature'];
  const body = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Check timestamp to prevent replay attacks
  const timestamp = parseInt(req.headers['sim-timestamp']);
  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
  
  if (timestamp < fiveMinutesAgo) {
    return res.status(401).send('Timestamp too old');
  }
  
  // Process the webhook
  const event = req.body;
  
  switch (event.type) {
    case 'workflow.execution.completed':
      const { workflowId, executionId, status, cost } = event.data;
      
      if (status === 'error') {
        console.error(`Workflow ${workflowId} failed: ${executionId}`);
        // Handle error...
      } else {
        console.log(`Workflow ${workflowId} completed: ${executionId}`);
        console.log(`Cost: $${cost.total}`);
        // Process successful execution...
      }
      break;
  }
  
  // Return 200 to acknowledge receipt
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});