L'API publique et le MCP server sont live.

API REST publique

api.freelance-os.fr, versionnée /v1. 177 opérations sur 26 domaines, en lecture et en écriture. Auth par clé X-API-Key (partners, scripts, mobile) ou jeton de session JWT (web et mobile). Le workspace est scopé automatiquement sur les clés, passé dans le path {workspaceId} sinon. Réponses en { data }, erreurs typées avec un code stable. Spec OpenAPI 3.1 et référence interactive live : api.freelance-os.fr/v1/docs.

• CRM : contacts, deals, segments, vue 360, interactions
• Workbench : projets, tâches, milestones, KPIs
• Counsel : devis, contrats, factures et lignes
• Booking et calendrier agrégé : agenda du jour, vue semaine et mois
• Inbox : threads, messages, conversations
• Studio, Collections, Programme, Products, Analytics
• Email, Calls, Webinars, LinkedIn, AI Visibility, Copilot
• Identity, plans publics, gestion des clés API

Fiabilité : idempotence, pagination, rate-limit

Pensé pour des clients mobiles et natifs sur réseau instable. Envoie un header Idempotency-Key sur tes POST, PATCH et DELETE : un retry rejoue la même réponse au lieu de créer en double. Les grosses listes (contacts, entrées, inbox, appels) se paginent au curseur : passe cursor et lis pagination.next_cursor jusqu'à has_more à false. Rate-limit 120 req/min en sliding window, headers X-RateLimit-* sur chaque réponse.

• Idempotency-Key : dedup des retries, 409 si un même appel est déjà en cours
• Pagination curseur keyset : { data, pagination: { next_cursor, has_more } }
• Rate-limit 120 req/min, 429 au dépassement

Serveur MCP

Un Model Context Protocol server hébergé. Tu connectes Freelance OS à Claude Code, Cursor, ChatGPT, Claude Desktop, en une commande depuis /settings/mcp. 200+ tools, OAuth 2.1 + DCR, JIT approval sur les actions destructives, audit log par workspace.

• Recherche full-text dans tous les modules
• Création de drafts depuis l'agent
• Lecture des transcripts d'appels
• Mutation des deals et tâches
• Workflows multi-modules orchestrés

Clés API

Génère des clés long-lived workspace-scopées depuis /settings/api-keys. Format fos_sk_live_<token>, hashes sha256 en DB, scopes (read:* / write:* / *), expiration optionnelle. Le plaintext s'affiche une seule fois. Une clé peut aussi nommer un site : c'est ce qu'exigent les routes /v1/end-user, par lesquelles ton application authentifie ses propres utilisateurs. Un client d'API n'a pas d'hôte d'où déduire le site, donc la clé le porte.

Authentifier les utilisateurs de ton app

Ton application a ses propres utilisateurs, et Freelance OS peut être leur backend d'authentification. Tu crées une clé qui nomme un de tes sites, ton app appelle /v1/end-user avec cette clé, et chaque personne inscrite appartient à ce site et à lui seul. La même adresse peut être cliente de deux de tes sites avec deux mots de passe différents, ou partager un seul compte si tu le demandes. Pour une app mobile, le SDK Google natif rend un jeton d'identité que tu postes tel quel : pas de redirection, pas de secret client, et la personne ressort avec son adresse vérifiée puisque Google vient de la prouver. L'inscription et la connexion rendent une paire de jetons : un jeton d'accès court, à mettre dans Authorization: Bearer, et un jeton de rafraîchissement à stocker. Le rafraîchissement fait tourner les deux, et un jeton déjà consommé qui reparaît coupe toute la lignée : la personne se reconnecte, l'éventuel voleur aussi, et personne ne reste dedans en silence.

• POST /v1/end-user/signup et /login : la paire de jetons
• POST /v1/end-user/oauth/google : le jeton du SDK Google natif, échangé contre la même paire
• POST /v1/end-user/refresh : rotation, et détection de rejeu
• GET /v1/end-user/me, PATCH pour le nom, DELETE pour le compte
• Mot de passe : /password/change, /password/reset-request, /password/reset-confirm
• Email : /verify-request et /verify-confirm, la vérification est par site
• Abonnements : GET /subscriptions, POST /subscriptions/cancel, POST /billing-portal

Stocker et lire les données de tes utilisateurs

Une collection est une table que tu définis dans Freelance OS, et tes utilisateurs peuvent y écrire depuis ton app. Deux lectures, jamais une seule : les enregistrements PUBLIÉS, que tout le monde voit, et les SIENS, qu'il est seul à voir. C'est la distinction qui évite le piège classique, une liste « mes éléments » qui rend en réalité ceux de tout le monde. Chaque écriture est bornée par la personne connectée : elle ne peut modifier ni supprimer un enregistrement qui n'est pas à elle, et une tentative rend 404, pas 403, parce qu'un 403 confirmerait que l'enregistrement existe. Les écritures sont plafonnées à 60 par minute et par collection, le même plafond que celui appliqué depuis un site, pour qu'une seconde surface ne contourne pas la première.

• GET /v1/end-user/collections : les collections ouvertes à ton audience
• GET /v1/end-user/collections/{slug}/records : les enregistrements publiés
• GET /v1/end-user/collections/{slug}/records/mine : les siens, publiés ou non
• POST /v1/end-user/collections/{slug}/records : en créer un
• PATCH et DELETE /v1/end-user/collections/{slug}/records/{recordId} : les siens uniquement

Les salons temps réel

Un salon est un espace que tes utilisateurs rejoignent en direct. Freelance OS tient l'identité et le droit d'entrer, un serveur média tient le son : tu demandes un jeton, tu le passes à ton SFU, et c'est tout. Le nom technique du salon est préfixé par ton site, donc deux clients qui appellent leur salon « general » ne se retrouvent jamais dans le même. Tu crées les salons depuis l'écran Salons d'un site, ou par le copilote. Un salon peut être réservé aux abonnés d'un de tes plans : la porte devient l'abonnement, vérifié au moment de la demande de jeton, et le jeton expire au bout d'une heure.

• GET /v1/end-user/rooms : les salons du site, et lesquels sont ouverts
• POST /v1/end-user/rooms/{slug}/token : le jeton d'entrée, et l'adresse du serveur média
• Un salon fermé refuse l'entrée sans disparaître de l'inventaire

Webhooks

Roadmap T3 2026. Configure des URLs cibles par workspace, choisis les événements à recevoir. Payload signé. Retry exponentiel. Logs d'événements visibles dans /settings/webhooks.

• contact.lifecycle_stage_changed
• deal.stage_changed
• invoice.paid
• booking.created
• draft.published

Connecter ton site

Branche n'importe quel site externe sur un formulaire Freelance OS sans refaire de back. Publie le formulaire, ajoute le domaine de ton site dans les origines autorisées du formulaire, puis copie les deux snippets depuis la page du formulaire : le POST vers /api/forms/submit (les leads tombent dans le CRM, les actions notif interne et confirmation prospect se déclenchent côté FOS) et le pixel px.js pour le tracking. Chaque formulaire est isolé par workspace, l'allowlist CORS aussi : deux workspaces ne se voient jamais.

• Origines autorisées : éditeur du formulaire, réglages, domaines
• Snippet submit + pixel : page du formulaire, à copier-coller
• GET /api/forms/schema?formId=... renvoie la forme des champs (id, label, type, options)
• Vérifie ton mapping au build de ton site pour bloquer toute dérive du formulaire

SDK

Client TypeScript auto-généré depuis la spec OpenAPI, type end-to-end. Pour les autres langages, utilise la spec OpenAPI 3.1 à api.freelance-os.fr/v1/openapi.json avec ton générateur préféré.