> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orsay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 🔑 API REST

> Accès programmatique à Orsay via clé API

## Vue d'ensemble

L'API REST Orsay vous permet de gérer vos séquences et d'accéder à vos conversations de manière programmatique depuis votre propre serveur. Cas d'usage :

* Automatiser la création de séquences depuis un VPS ou un cron
* Intégrer Orsay dans votre pipeline existant (ex : Instagram → DM séquence)
* Construire des automatisations personnalisées sans passer par le dashboard
* Récupérer les données de conversation pour votre CRM ou vos outils d'analytique

## Authentification

Toutes les requêtes API nécessitent un **Bearer token** avec votre clé API.

```bash theme={null}
curl -X GET https://client.api.prod.orsay.ai/api/v1/sequences \
  -H "Authorization: Bearer sk_live_votre_cle_api"
```

### Obtenir votre clé API

1. Allez dans **Settings → API Keys** dans le dashboard Orsay
2. Cliquez sur **Generate API Key**
3. Copiez la clé immédiatement — elle ne sera plus affichée

<Warning>
  Votre clé API donne un accès complet aux séquences de votre organisation. Gardez-la secrète et ne l'exposez jamais dans du code côté client.
</Warning>

## Rate Limiting

L'API est limitée à **200 requêtes par heure** par organisation.

Si vous dépassez cette limite, vous recevrez une réponse `429 Too Many Requests` avec un header `Retry-After` indiquant combien de secondes attendre.

## URL de base

```
https://client.api.prod.orsay.ai/api/v1
```

## Endpoints

### Lister les agents

```bash theme={null}
GET /agents
```

Retourne tous les agents IA de votre organisation.

**Réponse :**

```json theme={null}
[
  {
    "id": "e5f6g7h8-...",
    "name": "Agent Commercial",
    "is_published": true
  }
]
```

***

### Lister les profils

```bash theme={null}
GET /profiles
```

Retourne tous les profils Instagram et WhatsApp connectés.

**Réponse :**

```json theme={null}
{
  "instagram": [
    {
      "id": "12345678",
      "username": "monbusiness",
      "status": "CONNECTED"
    }
  ],
  "whatsapp": [
    {
      "id": "abcd-1234-...",
      "name": "Mon WhatsApp",
      "status": "CONNECTED"
    }
  ]
}
```

***

### Lister les séquences

```bash theme={null}
GET /sequences
```

Retourne toutes les séquences de votre organisation.

**Réponse :**

```json theme={null}
[
  {
    "id": "a1b2c3d4-...",
    "name": "Welcome DM",
    "trigger": "INSTAGRAM_MESSAGE",
    "channel": "INSTAGRAM",
    "active": true
  }
]
```

***

### Obtenir une séquence

```bash theme={null}
GET /sequences/{sequence_id}
```

Retourne les détails complets d'une séquence.

**Réponse :**

```json theme={null}
{
  "id": "a1b2c3d4-...",
  "name": "Welcome DM",
  "trigger": "INSTAGRAM_MESSAGE",
  "channel": "INSTAGRAM",
  "active": true,
  "type": "INBOUND",
  "agent_id": "e5f6g7h8-...",
  "profile_id": "12345",
  "inbound_response_delay": 5,
  "inbound_response_delay_unit": "MINUTES",
  "flow": [
    {
      "delay": 0,
      "delay_unit": "MINUTES",
      "content": "Bonjour ! Comment puis-je vous aider ?",
      "template_id": null,
      "action": null
    }
  ]
}
```

***

### Créer une séquence

```bash theme={null}
POST /sequences
```

**Corps de la requête :**

```json theme={null}
{
  "name": "Ma Nouvelle Séquence",
  "trigger": "INSTAGRAM_MESSAGE",
  "inbound_response_delay": 5,
  "inbound_response_delay_unit": "MINUTES",
  "agent_id": "e5f6g7h8-...",
  "profile_id": "12345",
  "active": false,
  "flow": [
    {
      "delay": 0,
      "delay_unit": "MINUTES",
      "followup_delays": [
        { "delay": 30, "delay_unit": "MINUTES" }
      ]
    }
  ]
}
```

**Champs requis :**

| Champ     | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `name`    | string | Nom de la séquence                    |
| `trigger` | string | Type de déclencheur (voir ci-dessous) |

**Champs optionnels :**

| Champ                                    | Type   | Défaut    | Description                              |
| ---------------------------------------- | ------ | --------- | ---------------------------------------- |
| `inbound_response_delay`                 | int    | 5         | Délai avant la première réponse          |
| `inbound_response_delay_unit`            | string | "MINUTES" | SECONDS, MINUTES ou HOURS                |
| `agent_id`                               | string | null      | ID de l'agent IA à utiliser              |
| `profile_id`                             | string | null      | ID du profil Instagram ou WhatsApp       |
| `active`                                 | bool   | false     | Si la séquence est active                |
| `flow`                                   | array  | \[]       | Définition des étapes du flow            |
| `filtering_agent`                        | string | null      | ID de l'agent de filtrage                |
| `should_continue_existing_conversations` | bool   | false     | Continuer les conversations existantes   |
| `keywords`                               | array  | null      | Mots-clés déclencheurs                   |
| `target_accounts`                        | array  | null      | Comptes cibles pour le scraping          |
| `enable_agent_on_conversation`           | bool   | true      | Activer l'agent IA sur les conversations |
| `require_manual_approval`                | bool   | false     | Approbation manuelle requise             |

**Réponse (201) :**

```json theme={null}
{
  "id": "new-sequence-uuid"
}
```

***

### Modifier une séquence

```bash theme={null}
PUT /sequences/{sequence_id}
```

Incluez uniquement les champs que vous souhaitez modifier.

**Corps de la requête :**

```json theme={null}
{
  "name": "Nom Mis à Jour",
  "active": true,
  "inbound_response_delay": 10
}
```

**Réponse :**

```json theme={null}
{
  "id": "a1b2c3d4-...",
  "status": "updated"
}
```

***

### Supprimer une séquence

```bash theme={null}
DELETE /sequences/{sequence_id}
```

**Réponse :**

```json theme={null}
{
  "status": "deleted"
}
```

***

### Lister les conversations

```bash theme={null}
GET /conversations
```

Retourne les conversations de votre organisation avec des filtres optionnels.

**Paramètres de requête :**

| Paramètre        | Type    | Défaut | Description                                                                         |
| ---------------- | ------- | ------ | ----------------------------------------------------------------------------------- |
| `classification` | string  | null   | Filtrer par classification : `positive`, `negative`, `undetermined`, `engaged`      |
| `is_active`      | boolean | null   | Filtrer par statut actif (`true`) ou inactif (`false`)                              |
| `since`          | string  | null   | Date ISO 8601 — retourne uniquement les conversations mises à jour après cette date |
| `page_size`      | int     | 20     | Nombre de résultats par page (max 50)                                               |
| `last_lead_id`   | string  | null   | Curseur pour la pagination (utiliser `next_cursor` de la réponse précédente)        |

**Exemple :**

```bash theme={null}
curl -X GET "https://client.api.prod.orsay.ai/api/v1/conversations?classification=positive&is_active=true&page_size=10" \
  -H "Authorization: Bearer sk_live_votre_cle_api"
```

**Réponse :**

```json theme={null}
{
  "conversations": [
    {
      "lead_id": "a1b2c3d4-...",
      "channel": "WHATSAPP",
      "classification": "positive",
      "is_active": true,
      "first_name": "Jean",
      "last_name": "Dupont",
      "username": null,
      "phone_number": "+33612345678",
      "latest_message_at": "2025-06-01T14:30:00+00:00",
      "latest_inbound_at": "2025-06-01T14:30:00+00:00",
      "latest_outbound_at": "2025-06-01T14:25:00+00:00"
    }
  ],
  "next_cursor": "a1b2c3d4-..."
}
```

<Note>
  Utilisez `next_cursor` comme paramètre `last_lead_id` dans les requêtes suivantes pour paginer les résultats. Quand `next_cursor` est `null`, il n'y a plus de résultats.
</Note>

***

### Obtenir les messages d'une conversation

```bash theme={null}
GET /conversations/{lead_id}
```

Retourne l'historique complet des messages d'une conversation.

**Paramètres de chemin :**

| Paramètre | Type | Description                     |
| --------- | ---- | ------------------------------- |
| `lead_id` | UUID | L'ID du lead de la conversation |

**Exemple :**

```bash theme={null}
curl -X GET "https://client.api.prod.orsay.ai/api/v1/conversations/a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "Authorization: Bearer sk_live_votre_cle_api"
```

**Réponse :**

```json theme={null}
{
  "lead_id": "a1b2c3d4-...",
  "channel": "WHATSAPP",
  "classification": "positive",
  "is_active": true,
  "lead": {
    "first_name": "Jean",
    "last_name": "Dupont",
    "username": null,
    "phone_number": "+33612345678"
  },
  "messages": [
    {
      "message_id": "msg-uuid-1",
      "content": "Bonjour ! Comment puis-je vous aider ?",
      "inbound": false,
      "timestamp": "2025-06-01T14:00:00+00:00",
      "status": "DELIVERED",
      "sent_by": "ai",
      "type": "CUSTOM"
    },
    {
      "message_id": "msg-uuid-2",
      "content": "Je voudrais en savoir plus sur vos services",
      "inbound": true,
      "timestamp": "2025-06-01T14:05:00+00:00",
      "status": null,
      "sent_by": null,
      "type": null
    }
  ],
  "total_messages": 2
}
```

## Types de déclencheurs

| Déclencheur                                     | Canal     | Type     |
| ----------------------------------------------- | --------- | -------- |
| `INSTAGRAM_MESSAGE`                             | Instagram | Inbound  |
| `INSTAGRAM_COMMENT`                             | Instagram | Outbound |
| `INSTAGRAM_STORY_REPLY`                         | Instagram | Inbound  |
| `INSTAGRAM_LEAD_FINDER_NEW_FOLLOWER`            | Instagram | Outbound |
| `INSTAGRAM_LEAD_FINDER_OTHER_ACCOUNT_FOLLOWERS` | Instagram | Outbound |
| `INSTAGRAM_LEAD_FINDER_NEW_LIKE`                | Instagram | Outbound |
| `INSTAGRAM_LEAD_FINDER_OTHER_ACCOUNT_COMMENT`   | Instagram | Outbound |
| `WHATSAPP_MESSAGE`                              | WhatsApp  | Inbound  |
| `CONTACT_CREATED`                               | WhatsApp  | Outbound |
| `CONTACT_SUBSCRIBED_TO_SEQUENCE`                | WhatsApp  | Outbound |

## Codes d'erreur

| Code  | Description                                                                       |
| ----- | --------------------------------------------------------------------------------- |
| `401` | Clé API invalide ou manquante                                                     |
| `404` | Ressource non trouvée (séquence ou conversation)                                  |
| `429` | Rate limit dépassé (200 req/heure)                                                |
| `400` | Requête invalide (mauvais trigger, champ manquant, format de date invalide, etc.) |

## Exemple : Pipeline complet

```python theme={null}
import requests
import time

API_KEY = "sk_live_votre_cle"
BASE_URL = "https://client.api.prod.orsay.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Lister les séquences
sequences = requests.get(f"{BASE_URL}/sequences", headers=HEADERS).json()
print(f"{len(sequences)} séquences trouvées")

# 2. Créer une nouvelle séquence
new_seq = requests.post(f"{BASE_URL}/sequences", headers=HEADERS, json={
    "name": "Pipeline Auto DM",
    "trigger": "INSTAGRAM_MESSAGE",
    "inbound_response_delay": 2,
    "inbound_response_delay_unit": "MINUTES",
    "agent_id": "votre-agent-id",
    "profile_id": "votre-profil-instagram-id",
    "active": True,
    "flow": [
        {
            "delay": 0,
            "delay_unit": "MINUTES",
            "followup_delays": [
                {"delay": 30, "delay_unit": "MINUTES"},
                {"delay": 120, "delay_unit": "MINUTES"}
            ]
        }
    ]
}).json()
print(f"Séquence créée : {new_seq['id']}")

# 3. La modifier plus tard
time.sleep(1)  # Petit délai entre les requêtes
requests.put(f"{BASE_URL}/sequences/{new_seq['id']}", headers=HEADERS, json={
    "name": "Pipeline Auto DM v2",
    "inbound_response_delay": 5,
})
```