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

# Métadonnées

> Attachez des paires clé-valeur personnalisées aux ressources de l’API

<Info>
  **Actuellement disponible pour les [Lots](/api-reference/batches/create).** Le support pour les extractions, explorations, cartes et réponses arrive bientôt.
</Info>

Les métadonnées vous permettent d'attacher des paires clé-valeur personnalisées aux ressources Olostep. Cela est utile pour le suivi, le filtrage, l'organisation et le stockage de contexte avec vos requêtes API.

Les métadonnées suivent l’approche de [Stripe](https://stripe.com/docs/api/metadata) — simple, flexible et cohérente sur tous les points de terminaison.

***

## Cas d'utilisation

<CardGroup cols={2}>
  <Card title="Suivi & Organisation" icon="folder">
    Liez les ressources à des systèmes internes avec des identifiants de commande, des identifiants de client ou des noms de projet.
  </Card>

  <Card title="Filtrage & Recherche" icon="magnifying-glass">
    Étiquetez les ressources pour un accès et un filtrage faciles dans votre application.
  </Card>

  <Card title="Contexte de Flux de Travail" icon="diagram-project">
    Stockez l'étape de pipeline, le niveau de priorité ou les instructions de traitement.
  </Card>

  <Card title="Piste d'Audit" icon="clock-rotate-left">
    Enregistrez qui a initié une requête, les horodatages ou les informations de version.
  </Card>
</CardGroup>

***

## Ajout de Métadonnées lors de la Création

Incluez le paramètre `metadata` lors de la création d'une ressource :

<CodeGroup>
  ```json Request Body theme={null}
  {
    "url": "https://example.com",
    "metadata": {
      "order_id": "12345",
      "customer_name": "John Doe",
      "priority": "high",
      "internal_ref": "proj-2024-001"
    }
  }
  ```

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

  response = requests.post(
      "https://api.olostep.com/v1/batches",
      headers={"Authorization": "Bearer <your_token>"},
      json={
          "items": [{"custom_id": "1", "url": "https://example.com"}],
          "metadata": {
              "project": "q4-analysis",
              "team": "data-ops",
              "priority": "high"
          }
      }
  )
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.olostep.com/v1/batches", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <your_token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      items: [{ custom_id: "1", url: "https://example.com" }],
      metadata: {
        project: "q4-analysis",
        team: "data-ops",
        priority: "high"
      }
    })
  });
  ```
</CodeGroup>

Les métadonnées sont renvoyées dans toutes les réponses GET ultérieures pour cette ressource.

***

## Règles de Validation

| Contrainte            | Limite                 | Exemple d'erreur                                                                             |
| --------------------- | ---------------------- | -------------------------------------------------------------------------------------------- |
| Clés maximum          | 50                     | `"Les métadonnées peuvent avoir un maximum de 50 clés. Vous avez fourni 51 clés."`           |
| Longueur de la clé    | 40 caractères          | `"La clé de métadonnée \"my_very_long_key_name...\" dépasse la limite de 40 caractères."`    |
| Format de la clé      | Pas de crochets        | `"La clé de métadonnée \"items[0]\" ne peut pas contenir de crochets ([ ou ])."`             |
| Longueur de la valeur | 500 caractères         | `"La valeur de métadonnée pour la clé \"description\" dépasse la limite de 500 caractères."` |
| Type de valeur        | Uniquement des chaînes | `"La valeur de métadonnée pour la clé \"count\" doit être une chaîne. Objet reçu."`          |

<Note>
  **Conversion de Type** : Les nombres et les booléens sont automatiquement convertis en chaînes.

  * `42` → `"42"`
  * `true` → `"true"`
  * `3.14` → `"3.14"`

  Les objets et les tableaux sont rejetés.
</Note>

***

## Mise à Jour des Métadonnées (PATCH)

<Info>
  **Actuellement disponible pour :** uniquement les [Lots](/api-reference/batches/update).

  Les explorations, extractions, cartes et réponses ne supportent pas encore la mise à jour des métadonnées après création.
</Info>

Vous pouvez mettre à jour les métadonnées sur des lots existants en utilisant le [point de terminaison PATCH](/api-reference/batches/update). Les mises à jour utilisent un comportement de fusion.

### Opérations de Mise à Jour

<AccordionGroup>
  <Accordion title="Ajouter de nouvelles clés" icon="plus">
    De nouvelles clés sont ajoutées tout en préservant les existantes.

    ```bash theme={null}
    curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
      -H "Authorization: Bearer <your_token>" \
      -H "Content-Type: application/json" \
      -d '{"metadata": {"new_key": "new_value"}}'
    ```

    **Avant :** `{"project": "alpha"}`\
    **Après :** `{"project": "alpha", "new_key": "new_value"}`
  </Accordion>

  <Accordion title="Mettre à jour les clés existantes" icon="pen">
    Les clés existantes sont écrasées avec de nouvelles valeurs.

    ```bash theme={null}
    curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
      -H "Authorization: Bearer <your_token>" \
      -H "Content-Type: application/json" \
      -d '{"metadata": {"project": "beta"}}'
    ```

    **Avant :** `{"project": "alpha", "priority": "high"}`\
    **Après :** `{"project": "beta", "priority": "high"}`
  </Accordion>

  <Accordion title="Supprimer des clés spécifiques" icon="trash">
    Attribuez à une clé la valeur `null` ou `""` (chaîne vide) pour la supprimer.

    ```bash theme={null}
    curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
      -H "Authorization: Bearer <your_token>" \
      -H "Content-Type: application/json" \
      -d '{"metadata": {"priority": null}}'
    ```

    **Avant :** `{"project": "alpha", "priority": "high"}`\
    **Après :** `{"project": "alpha"}`
  </Accordion>

  <Accordion title="Effacer toutes les métadonnées" icon="eraser">
    Attribuez au champ entier des métadonnées la valeur `null` ou `""` pour supprimer toutes les clés.

    ```bash theme={null}
    curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
      -H "Authorization: Bearer <your_token>" \
      -H "Content-Type: application/json" \
      -d '{"metadata": null}'
    ```

    **Avant :** `{"project": "alpha", "priority": "high"}`\
    **Après :** `{}`
  </Accordion>

  <Accordion title="Opérations mixtes" icon="shuffle">
    Ajoutez, mettez à jour et supprimez des clés dans une seule requête.

    ```bash theme={null}
    curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
      -H "Authorization: Bearer <your_token>" \
      -H "Content-Type: application/json" \
      -d '{"metadata": {"project": "gamma", "new_field": "value", "old_field": null}}'
    ```

    **Avant :** `{"project": "alpha", "old_field": "remove_me"}`\
    **Après :** `{"project": "gamma", "new_field": "value"}`
  </Accordion>
</AccordionGroup>

### Résumé du Comportement PATCH

| Opération             | Requête                                   | Résultat                           |
| --------------------- | ----------------------------------------- | ---------------------------------- |
| Ajouter une clé       | `{"metadata": {"new": "value"}}`          | Clé ajoutée, autres préservées     |
| Mettre à jour une clé | `{"metadata": {"existing": "new_value"}}` | Clé mise à jour, autres préservées |
| Supprimer une clé     | `{"metadata": {"key": null}}`             | Clé supprimée, autres préservées   |
| Supprimer une clé     | `{"metadata": {"key": ""}}`               | Clé supprimée, autres préservées   |
| Effacer tout          | `{"metadata": null}`                      | Toutes les clés supprimées         |
| Effacer tout          | `{"metadata": ""}`                        | Toutes les clés supprimées         |
| Pas de changement     | `{"metadata": {}}`                        | Aucun changement                   |