Référence API & MCP

Introduction

L'API REST OSTRATA permet aux systèmes externes de lire et d'écrire les données de l'espace de travail : objets personnalisés, champs et enregistrements. Elle reprend le même modèle de permissions que les membres de l'espace — chaque clé d'intégration est liée à un profil de permissions qui contrôle ce que la clé peut faire.

L'API est versionnée sous /api/v1. Les changements incompatibles seront publiés sous un nouveau préfixe de version ; les ajouts non rupturistes restent sur v1.

Authentification

Chaque requête doit inclure une clé API d'intégration de l'espace de travail dans l'en-tête Authorization. Les clés sont créées par un administrateur dans Configuration → API et ne sont affichées qu'une seule fois à la création.

Les clés révoquées sont rejetées immédiatement. Les clés n'expirent pas automatiquement — faites une rotation en créant une nouvelle clé et en révoquant l'ancienne.

• Les clés commencent par le préfixe osk_.
• Ne commitez jamais de clés dans le code source et ne les exposez pas dans des applications côté client.
• Attribuez le profil de permissions le plus restrictif qui satisfait l'intégration.

Authorization: Bearer osk_YOUR_SECRET_KEY

Premiers pas

Vous avez besoin d'une clé API créée par un administrateur de l'espace de travail. Si vous développez une intégration pour l'espace d'un client, demandez à son administrateur de créer un profil de permissions dédié (Configuration → Permissions) et une clé d'intégration (Configuration → API) avec ce profil.

Remplacez l'URL de base ci-dessous par l'origine de votre déploiement OSTRATA (le même hôte que dans le navigateur).

curl -s -H "Authorization: Bearer osk_YOUR_KEY" \
  "https://ostrata.io/api/v1/objects/contacts/records?limit=5"

curl -s -X POST \
  -H "Authorization: Bearer osk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","fields":{"email":"jane@example.com"}}' \
  "https://ostrata.io/api/v1/objects/contacts/records"

Requêtes et réponses

Les corps de requête et de réponse sont en JSON. Utilisez Content-Type: application/json sur les requêtes POST et PATCH avec un corps.

Les réponses réussies utilisent une enveloppe data. Les erreurs utilisent un objet error avec code et message.

• unauthorized (401) — clé API manquante ou invalide
• forbidden (403) — clé valide mais action non autorisée par le profil
• not_found (404) — objet, champ ou enregistrement introuvable
• bad_request (400) — échec de validation
• conflict (409) — nom ou nom API en doublon

{
  "data": { "record": { "id": "…", "name": "Jane Doe", "fields": {} } }
}

{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have permission for this action."
  }
}

Permissions

L'autorisation est appliquée à partir du profil de permissions attaché à la clé API — et non de l'administrateur qui a créé la clé. Créez des profils restrictifs pour les intégrations (p. ex. « Zapier — sync contacts ») avec uniquement les droits objet, champ et enregistrement requis.

Les réponses d'enregistrements omettent les valeurs de champs que le profil ne peut pas lire. Les requêtes de création et de mise à jour ignorent les champs que le profil ne peut pas modifier.

• object.create / object.update / object.delete — modifications d'objets au niveau schéma
• field.create / field.update / field.delete — définitions de champs sur les objets
• Consultation / création / mise à jour / suppression d'enregistrements par objet — configurées dans la matrice du profil
• Lecture / modification par champ — surcharges optionnelles par objet

Objets et champs

Les objets sont adressés par apiName (p. ex. contacts, deals, projects). Les champs utilisent apiName au sein de leur objet parent.

Les objets CRM standard sont fournis avec chaque espace de travail. Les objets personnalisés sont créés via l'API ou l'interface Configuration.

Enregistrements

Les enregistrements exposent un name plus un objet fields (correspond aux données personnalisées stockées). Les champs de recherche et d'adresse utilisent les mêmes conventions de clés que l'interface OSTRATA.

La liste des enregistrements prend en charge limit (1–100), offset (0–10 000) et q pour la recherche textuelle. Les réponses incluent count, offset, limit et hasMore pour la pagination.

Pour les migrations volumineuses, utilisez les tâches d'import en masse sous /import/jobs plutôt que de créer les enregistrements un par un.

Import en masse

L'import en masse reprend Configuration → Import de données : créez une tâche, mappez les colonnes, validez chaque ligne, puis exécutez. Nécessite un profil de permissions administrateur sur la clé API.

Les mêmes limites s'appliquent : fichiers de 10 Mo, 10 000 lignes de données, un objet principal par tâche, un objet lié embarqué optionnel. La validation est tout-ou-rien — pas d'écritures partielles.

Flux : POST /import/jobs → PATCH mappages (optionnel) → POST …/validate → POST …/run. Les tâches s'exécutent en arrière-plan ; interrogez GET …/jobs/:jobId pour le statut.

• Corps JSON — fournissez headers et rows directement (max. 10 000 lignes)
• Multipart — téléversez un CSV ou Excel (.csv, .xlsx, .xls) avec le champ de formulaire primaryObjectApiName
• Objets standard et personnalisés — primaryObjectApiName correspond aux noms API des objets
• embedded — créez/mettez à jour des enregistrements liés depuis les mêmes lignes et liez via un champ de recherche
• duplicateMode — create, skip ou update (Contacts correspond par e-mail/téléphone ; les objets basés sur le nom correspondent par nom normalisé)
• Les champs auto-numérotés sont générés par le système ; les totaux de devis calculés ne peuvent pas être importés
• Les événements se synchronisent avec Google Calendar lorsque l'acteur de la clé API a un calendrier connecté

curl -s -X POST \
  -H "Authorization: Bearer osk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"contacts.csv","headers":["email"],"rows":[{"email":"ada@example.com","first_name":"Ada","last_name":"Lovelace"}],"primaryObjectApiName":"contacts","duplicateMode":"update"}' \
  "https://ostrata.io/api/v1/import/jobs"

curl -s -X POST \
  -H "Authorization: Bearer osk_YOUR_KEY" \
  "https://ostrata.io/api/v1/import/jobs/JOB_ID/validate"

curl -s -X POST \
  -H "Authorization: Bearer osk_YOUR_KEY" \
  "https://ostrata.io/api/v1/import/jobs/JOB_ID/run"

Vue d'ensemble

OSTRATA expose un serveur MCP distant pour que Claude, Cursor et d'autres clients MCP puissent rechercher et mettre à jour vos données CRM.

Chaque membre crée sa propre connexion depuis Espace personnel → MCP. Les clés utilisent le préfixe omk_ et héritent du profil de permissions du membre — les mêmes limites qu'Opérations.

Authentification

Envoyez Authorization: Bearer omk_VOTRE_CLE pour Claude Code ou Cursor.

Claude Desktop et Claude web utilisent OAuth : collez OAuth Client ID et Secret dans les réglages avancés, puis connectez-vous lorsque Claude le demande.

Les clés MCP membre (omk_) fonctionnent uniquement sur /api/mcp. Les clés d'intégration REST admin (osk_) fonctionnent uniquement sur /api/v1 — produits séparés.

Claude (connecteur personnalisé)

Dans Claude Desktop ou Claude web : Réglages → Connecteurs → Ajouter un connecteur personnalisé. Collez le nom, l'URL, l'OAuth Client ID et l'OAuth Client Secret depuis Espace personnel → MCP.

Lors de la connexion, Claude ouvre le navigateur pour vous connecter à OSTRATA — même compte membre que celui qui a créé la connexion.

Nom : OSTRATA
URL du serveur MCP distant : https://ostrata.io/api/mcp
OAuth Client ID : omc_…
OAuth Client Secret : ocs_…

Claude Code

Transport HTTP natif — aucun proxy requis.

claude mcp add --transport http ostrata https://ostrata.io/api/mcp \
  --header "Authorization: Bearer omk_YOUR_KEY"

Cursor

Ajoutez dans Réglages Cursor → MCP.

{
  "mcpServers": {
    "ostrata": {
      "url": "https://ostrata.io/api/mcp",
      "headers": {
        "Authorization": "Bearer omk_YOUR_KEY"
      }
    }
  }
}

Outils

Appelez list_objects en premier pour découvrir les apiNames. search_records accepte query (recherche texte), des filtres structurés comme Pilot, et la pagination via offset + limit (50 max par page).

• list_objects — List visible CRM object types and readable fields.
• describe_object — Get one object schema by apiName.
• search_records — Search records with query, filters, and offset/limit pagination.
• get_record — Read one record.
• create_record — Create a record (created_by = connection owner).
• update_record — Update record fields.
• delete_record — Delete a record.
• list_related_records — List child records linked via lookups.
• create_object — Create a custom object.
• update_object — Update object metadata.
• delete_object — Delete a custom object.
• add_field — Add a field to an object.
• update_field — Update a field definition.
• remove_field — Remove a field.
• list_import_jobs — List bulk import jobs (admin profile).
• create_import_job — Create import job draft.
• get_import_job — Get import job detail.
• validate_import_job — Validate import mappings.
• run_import_job — Execute import job.
• list_attachments — List files on a record.
• upload_attachment — Upload base64 file to a record.
• delete_attachment — Delete an attachment.
• draft_email_to_contact — AI draft email to a CRM contact.
• send_email — Send email from connection owner's Gmail.

Points de terminaison

Tous les chemins ci-dessous sont relatifs à /api/v1. Les segments de chemin en italique (p. ex. :objectApiName) sont remplacés par des valeurs réelles.

Renvoie tous les types d'objets que la clé API peut consulter, y compris les objets CRM standard (Contacts, Affaires, etc.) et les objets personnalisés. Chaque objet inclut des métadonnées de champs lisibles.

{
  "data": {
    "objects": [
      {
        "apiName": "contacts",
        "name": "Contacts",
        "isDefault": true,
        "fields": [
          {
            "apiName": "email",
            "name": "Email",
            "type": "email",
            "required": false
          }
        ]
      }
    ]
  }
}

curl -H "Authorization: Bearer osk_YOUR_KEY" \
  "https://ostrata.io/api/v1/objects"

Crée un nouveau type d'objet personnalisé dans l'espace de travail. Nécessite object.create sur le profil de permissions de la clé.

{
  "name": "Projects",
  "apiName": "projects",
  "attachmentsEnabled": true
}

{
  "data": {
    "object": {
      "apiName": "projects",
      "name": "Projects",
      "isDefault": false,
      "fields": []
    }
  }
}

curl -X POST -H "Authorization: Bearer osk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Projects","apiName":"projects"}' \
  "https://ostrata.io/api/v1/objects"

Récupère un objet par son nom API, y compris les définitions de champs que la clé peut lire.

Paramètres de chemin

Met à jour le nom d'affichage et/ou le nom API d'un objet.

Paramètres de chemin

{
  "name": "Customers",
  "apiName": "customers"
}

Supprime un objet personnalisé et son schéma. Les objets CRM par défaut ne peuvent pas être supprimés.

Paramètres de chemin

{
  "data": {
    "deleted": true
  }
}

Liste les définitions de champs d'un objet que la clé API peut lire.

Paramètres de chemin

Ajoute un nouveau champ au schéma d'un objet.

Paramètres de chemin

{
  "name": "Industry",
  "apiName": "industry",
  "type": "select",
  "required": false,
  "selectOptions": [
    {
      "label": "SaaS",
      "apiName": "saas"
    }
  ]
}

Renvoie une définition de champ.

Paramètres de chemin

Met à jour le libellé, le nom API, le type, les options de sélection ou le code devise du champ.

Paramètres de chemin

{
  "name": "Industry segment"
}

Supprime un champ défini par l'utilisateur d'un objet.

Paramètres de chemin

Liste les enregistrements d'un objet. Les valeurs de champs dans les réponses sont filtrées selon ce que la clé peut lire.

Paramètres de chemin

Paramètres de requête

{
  "data": {
    "records": [
      {
        "id": "uuid",
        "name": "Jane Doe",
        "fields": {
          "email": "jane@example.com"
        }
      }
    ],
    "count": 1,
    "offset": 0,
    "limit": 25,
    "hasMore": false
  }
}

curl -H "Authorization: Bearer osk_YOUR_KEY" \
  "https://ostrata.io/api/v1/objects/contacts/records?limit=20&offset=0"

Crée un enregistrement. Les champs modifiables sont limités par le profil de permissions.

Paramètres de chemin

{
  "name": "Jane Doe",
  "fields": {
    "email": "jane@example.com",
    "status": "active"
  }
}

curl -X POST -H "Authorization: Bearer osk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","fields":{"email":"jane@example.com"}}' \
  "https://ostrata.io/api/v1/objects/contacts/records"

Renvoie un enregistrement par UUID.

Paramètres de chemin

Met à jour le nom et/ou les valeurs de champs de l'enregistrement.

Paramètres de chemin

{
  "fields": {
    "status": "customer"
  }
}

Supprime définitivement un enregistrement.

Paramètres de chemin

Liste les tâches d'import en masse de l'espace de travail. Nécessite un profil de permissions administrateur sur la clé API.

Paramètres de requête

{
  "data": {
    "jobs": [
      {
        "id": "…",
        "fileName": "contacts.csv",
        "status": "succeeded",
        "rowCount": 120,
        "primaryObject": {
          "apiName": "contacts",
          "name": "Contacts"
        }
      }
    ]
  }
}

curl -H "Authorization: Bearer osk_YOUR_KEY" \
  "https://ostrata.io/api/v1/import/jobs?limit=25"

Crée une tâche d'import en masse. Envoyez du JSON avec headers et rows, ou du multipart/form-data avec un champ file plus primaryObjectApiName. Abandonne les autres sessions brouillon pour l'acteur de la clé. Mêmes règles de validation et de doublons que Configuration → Import de données.

{
  "fileName": "contacts.csv",
  "headers": [
    "first_name",
    "last_name",
    "email"
  ],
  "rows": [
    {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com"
    }
  ],
  "primaryObjectApiName": "contacts",
  "sourceType": "external_crm",
  "duplicateMode": "update",
  "primaryMappings": [
    {
      "fileColumn": "first_name",
      "fieldApiName": "first_name"
    },
    {
      "fileColumn": "email",
      "fieldApiName": "email"
    }
  ],
  "embedded": {
    "enabled": true,
    "objectApiName": "companies",
    "linkFieldApiName": "company",
    "matchKeyColumn": "company_name",
    "mappings": [
      {
        "fileColumn": "company_name",
        "fieldApiName": "name"
      }
    ]
  }
}

{
  "data": {
    "job": {
      "id": "…",
      "status": "draft",
      "primaryObject": {
        "apiName": "contacts",
        "name": "Contacts"
      }
    }
  }
}

curl -X POST -H "Authorization: Bearer osk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"contacts.csv","headers":["first_name","email"],"rows":[{"first_name":"Ada","email":"ada@example.com"}],"primaryObjectApiName":"contacts"}' \
  "https://ostrata.io/api/v1/import/jobs"

Renvoie une tâche d'import avec sa configuration, le résultat de validation et le résumé final une fois terminée.

Paramètres de chemin

Met à jour le type de source, l'objet principal, le mode de doublon, les mappages de colonnes ou la configuration d'objet embarqué.

Paramètres de chemin

{
  "duplicateMode": "update",
  "primaryMappings": [
    {
      "fileColumn": "email",
      "fieldApiName": "email"
    }
  ]
}

Supprime une tâche d'import de l'historique. Impossible de supprimer une tâche en cours d'exécution.

Paramètres de chemin

{
  "data": {
    "deleted": true
  }
}

Exécute une simulation tout-ou-rien sur chaque ligne. En cas de succès, le statut de la tâche devient validated et elle peut être exécutée.

Paramètres de chemin

Exécute une tâche d'import validée en arrière-plan. Renvoie 202 Accepted lorsque la plateforme prend en charge le travail différé ; sinon attend et renvoie la tâche terminée.

Paramètres de chemin

{
  "data": {
    "jobId": "…",
    "status": "running"
  }
}

curl -X POST -H "Authorization: Bearer osk_YOUR_KEY" \
  "https://ostrata.io/api/v1/import/jobs/JOB_UUID/run"