~ macha · API pour développeurs

Construisez des agents de support depuis votre terminal.

Utilisez Macha directement depuis votre coding agent. Donnez-lui votre clé d'API et livrez un agent fonctionnel, avec connecteurs, outils et triggers, sans quitter la ligne de commande.

Démarrer l'essai gratuit Lire la doc de l'API

Fonctionne avec Claude Code Codex Cursor

claude, crée un agent Macha

Bienvenue dans Claude Code

Opus 4.8 · ~/macha-agents

> Voici ma clé Macha : mka_live_••••

Crée un agent WISMO sur Shopify + Zendesk.

● Lire le contrat de l'API Macha

┗ llms-full.txt · OpenAPI 3.1

● GET /connectors

┗ shopify · zendesk · stripe

● POST /agents → @wismo

┗ { id: "agent_7Qh2…", tools: 3, is_active: true }

✓ Créé @wismo · en direct sur votre tableau de bord

Apportez votre propre coding agent.

L'API est du HTTP simple avec des docs que les modèles peuvent lire, n'importe quel outil agentic de code peut lire le contrat et construire dessus.

Claude Code

Pointez-le sur llms-full.txt + votre clé, il lit le contrat et construit.

$ claude "read $MACHA/llms-full.txt"

Codex

Pointez-le sur llms-full.txt + votre clé, il lit le contrat et construit.

$ codex --doc $MACHA/openapi.json

Cursor

Pointez-le sur llms-full.txt + votre clé, il lit le contrat et construit.

@Docs → getmacha.com/llms-full.txt

Ils marchent tous pour la même raison : HTTP + llms.txt + OpenAPI. Aucun lock-in de SDK, le même flux tourne depuis cURL ou n'importe quel client HTTP.

Tout ce qu'un coding agent doit avoir pour piloter Macha.

Une surface REST propre, des clés à moindre privilège, une doc écrite pour être lue par une machine.

Une vraie API REST

Auth Bearer, une enveloppe { data, meta }, des codes d'erreur stables, des écritures idempotentes et des limites de 1 000/min · 10 000/h.

https://dashboard.getmacha.com/api/v1

Clés à scope

Émettez des clés mka_live_… depuis Paramètres → API Keys avec des scopes {resource}:{action}. Moindre privilège, scope organisation, affichées une seule fois (hachées avec bcrypt).

mka_live_•••• · agents:write

Docs lisibles par IA

llms.txt + llms-full.txt sur www.getmacha.com, plus une spec OpenAPI 3.1 avec x-required-scope sur chaque opération.

/api/v1/openapi.json

De la clé à l'agent qui tourne, en une session.

1

Générez une clé à scope

Dans Paramètres → API Keys, émettez une clé mka_live_ avec juste les scopes dont vous avez besoin. Elle est affichée une seule fois.
2

Pointez votre coding agent sur la doc

Déposez llms-full.txt + la spec OpenAPI dans Claude Code ou Codex et définissez MACHA_API_KEY.
3

Il liste les connecteurs pour trouver les outils

L'agent appelle GET /connectors pour connaître les vrais noms d'outils dans votre org, sans deviner.
4

Il fait un /agents pour le créer

Un seul POST /agents idempotent branche instructions et outils. La réponse contient le nouvel agent ID.

claude, crée un agent WISMO

$ export MACHA_API_KEY=mka_live_••••
$ curl -s $MACHA/api/v1/connectors
  → shopify · zendesk · …
$ curl -s -X POST $MACHA/api/v1/agents -d '{
    "handle":"wismo", "tools":[
      "shopify_get_order",
      "shopify_search_orders",
      "zendesk_add_public_reply" ] }'
  { "data":{ "id":"agent_7Qh2…", "handle":"@wismo",
    "model":"claude-sonnet", "tools_count":3 } }
✓ created

Ce contre quoi vous pouvez construire.

Une carte honnête de la surface v1. La config et le contenu sont programmables ; le runtime en direct, la facturation et les surfaces critiques restent dans le tableau de bord, exprès.

Agents

CRUD complet

Créer, lire, mettre à jour, supprimer, les instructions et les outils que chaque agent peut appeler.

Custom tools

CRUD complet

Enregistrez votre propre API REST comme outils d'agents avec POST /custom_tools.

Sources

CRUD complet

Gérez les sources de connaissance derrière vos agents de manière programmatique.

Conversations

Lecture

Paginez l'historique des conversations vers votre entrepôt. Lecture seule, pagination par curseur.

Connecteurs

Lecture

Listez les connecteurs et leurs noms d'outils câblés dans votre org.

En v1, les triggers sont en lecture seule, configurez les triggers webhook et planifiés dans le tableau de bord, puis relisez-les via l'API. Faire tourner un tour de chat en direct, la facturation, Studies et Sidekick restent uniquement dans le tableau de bord, par conception.

Pourquoi une IA peut réellement le piloter.

✓
Une enveloppe de réponse partout. Chaque endpoint renvoie { data, meta } avec un request_id et un next_cursor. Apprenez la forme une fois.
✓
Codes d'erreur stables, exploitables par machine. Les erreurs portent un code stable, pas juste du texte.
✓
Les scopes se découvrent. Un 403 plus x-required-scope indique à l'agent exactement quel scope vous demander.
✓
Les retries idempotents ne dupliquent pas. Les écritures respectent un Idempotency-Key avec replay de 24h.

Une enveloppe, partout

{ "data": { … },
  "meta": { "request_id":"req_a1b2c3",
          "next_cursor":"eyJpZ…" } }

Erreurs sur lesquelles un modèle peut brancher

{ "error": {
    "code":"insufficient_scope",
    "message":"needs agents:write" } }

Des garde-fous qui rendent la délégation sûre.

Confier une clé à un agent autonome ne marche que si le rayon de dégât est petit, réversible et auditable.

safe-to-delegate

✓
Clés à moindre privilège — une clé ne fait que ce que vous avez accordé.
✓
Écritures idempotentes — Idempotency-Key garantit que les retries ne dupliquent pas.
✓
Rate limits par clé — 1 000/min · 10 000/h, avec Retry-After en 429.
✓
Suppression douce — les suppressions atterrissent dans une corbeille 30 jours avec restauration en un clic.
✓
Piste d'audit — chaque action de l'API est étiquetée « créé via clé API <label> ».
✓
Auto-révocation sur fuite — le préfixe mka_live_ est scanné sur GitHub public et révoqué automatiquement.

Au-delà d'un seul agent.

Une fois que c'est une API, toute votre boîte à outils de workflow s'applique.

Agents-as-code dans Git

Gardez les définitions d'agents dans votre repo et faites faire un PATCH /agents à la CI au moment du merge. Revoyez les changements de prompt comme du code.

Câblage en masse

Lancez un sous-agent par gamme de produits dans une boucle, des heures de clics deviennent un script.

Votre propre API comme outils

Enregistrez des endpoints REST internes avec POST /custom_tools pour que les agents appellent vos systèmes.

Conversations vers votre entrepôt

Paginez GET /conversations avec le curseur vers BigQuery ou Snowflake.

.github/workflows/agents.yml

# synchronise la config d'agent à chaque merge sur main
$ curl -X PATCH $MACHA/api/v1/agents/$ID \
    -H "Idempotency-Key: $GITHUB_SHA" \
    --data @agents/wismo.json
✓ wismo mis à jour · req_4f8a…

// coût

L'API est gratuite. Construire et gérer des agents via l'API coûte zéro crédit, aucune facturation, sur tous les comptes, y compris les essais. Vous ne dépensez des crédits que quand un agent que vous avez construit tourne vraiment (traite un ticket ou se déclenche sur un trigger).

Que pourriez-vous construire avec l' API Macha ?

Obtenez votre clé API → # puis collez votre clé dans Claude Code, Codex ou Cursor

Ou lisez la documentation de l'API.

Questions fréquentes.

Ce que l'API peut et ne peut pas faire, comment elle est sécurisée, et avec quels coding agents elle marche.

Oui, parce que la clé ne porte que les scopes que vous accordez, et elle est de portée organisation. Donnez à un agent de découverte une clé lecture seule ; réservez agents:write pour quand vous voulez vraiment qu'il construise. Les suppressions sont douces (corbeille 30 jours), l'idempotence empêche les doublons, chaque changement est audité avec un request_id et le label de la clé, et le préfixe mka_live_ est scanné par GitHub et GitGuardian, donc une clé fuitée s'auto-révoque.

En v1, triggers, chatbots, team, analytics et org sont en lecture seule, vous configurez les triggers webhook et planifiés dans le tableau de bord, puis vous les relisez par l'API. Faire tourner un tour de chat en direct, la facturation, Studies et Sidekick sont réservés au tableau de bord, par conception. L'API sert à construire et gérer des agents (agents, custom tools et sources sont CRUD complet), pas à servir une conversation en temps réel.

L'API elle-même est gratuite. Générer des clés et les utiliser pour construire et gérer des agents, connecteurs, outils et sources coûte zéro crédit, aucun coût par appel ni facturation d'API, et c'est disponible sur tous les comptes, y compris les essais. C'est parce que l'API est une couche de gestion, pas d'exécution : elle configure les agents dans votre tableau de bord, elle ne les fait pas tourner. Les crédits ne sont dépensés que quand un agent tourne, se déclenche sur un trigger ou traite un ticket et prend de vraies actions. Ce coût runtime est en crédits (par action IA, par modèle) et il est le même que l'agent ait été construit à la main ou via l'API.

N'importe quel agent capable d'exécuter des commandes shell et de lire une URL. Claude Code, Codex et Cursor sont les plus évidents : pointez-les sur llms-full.txt et la spec OpenAPI, définissez MACHA_API_KEY dans l'environnement, ils ont tout ce qu'il faut pour découvrir vos connecteurs et créer des agents. Comme c'est une API REST simple derrière un jeton Bearer, le même flux marche depuis n'importe quel script ou framework.

Chaque clé est limitée à un ensemble de scopes {ressource}:{action}, par exemple agents:read et agents:write. Chaque opération de la spec OpenAPI déclare le scope requis via x-required-scope, donc un agent voit ce que l'appel requiert avant de le faire. Si la clé n'a pas le scope, l'appel renvoie 403 insufficient_scope en nommant exactement ce qu'il faut, l'agent peut alors vous demander d'élargir la clé.

Confiez votre clé à votre coding agent. Commencez à construire.

Démarrer l'essai gratuit Lire la doc de l'API

500 crédits gratuits · sans limite de temps, sans carte