Documentation API Inkpilots V1

Objectif : Référence API complète pour l’API publique V1, avec descriptions détaillées des endpoints, paramètres de requête, authentification, formats de réponse et système de quotas pour la génération du SDK Node.js.

Table des matières

Authentification
URL de base et CORS
Endpoints API
Gestion des erreurs
Système de quotas
Formats de réponse
Résumé des endpoints

Authentification

Authentification par clé API

Tous les endpoints de l’API V1 nécessitent une authentification via clé API. La clé API doit être transmise dans les en-têtes de la requête.

Format de l’en-tête :

x-api-key: Bearer <your-api-key>

Exemple :

curl -H "x-api-key: Bearer your_api_key_here" https://inkpilots.com/api/v1/agents

Flux de vérification

Le client envoie la requête avec l’en-tête x-api-key
Le serveur appelle la fonction verifyApiKey(apiKeyHeader)
Si la clé est valide, la réponse contient :
- isValid : booléen
- workspaceId : string (ObjectId MongoDB sous forme de chaîne)
Si la clé est invalide, la réponse est { isValid: false }

Réponses d’erreur

401 Unauthorized : Clé API invalide ou manquante, ou permissions insuffisantes
402 Payment Required : Quota d’accès API dépassé pour le plan de l’espace de travail

URL de base et CORS

URL de base

https://inkpilots.com/api/v1

En-têtes CORS

Toutes les réponses incluent les en-têtes CORS suivants :

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, x-api-key

Remarque : CORS autorise toutes les origines car l’API n’utilise pas de cookies (authentification stateless).

Requêtes preflight

Tous les endpoints prennent en charge les requêtes OPTIONS pour le preflight CORS :

curl -X OPTIONS https://inkpilots.com/api/v1/agents

Réponse : 204 No Content avec les en-têtes CORS.

Endpoints API

1. Lister les agents

Endpoint : GET /agents

Résumé : Lister les agents

Description : Récupère une liste paginée d’agents avec un filtrage avancé par statut, mode d’exécution, modèle LLM et recherche plein texte sur le nom et le prompt. Nécessite une authentification via l’en-tête x-api-key et un quota API valide.

Authentification : Requise (x-api-key)

Tags : Agents

Paramètres de requête :

Paramètre	Type	Par défaut	Description	Exemple
skip	number	0	Nombre d’agents à ignorer pour la pagination (offset)	0
limit	number	10	Nombre maximal d’agents à retourner par page (plafonné à 100)	20
sortBy	string	createdAt	Champ utilisé pour trier les agents (ex. : name, createdAt, model, isActive)	createdAt
sortOrder	enum	desc	Ordre de tri (croissant ou décroissant)	desc
status	enum	optional	Filtrer les agents par statut (active ou inactive)	active
executionMode	enum	optional	Filtrer les agents par mode d’exécution (scheduled ou batched)	scheduled
model	string	optional	Filtrer les agents par nom de modèle LLM	llama-2-70b-chat
search	string	optional	Recherche plein texte dans le nom et le prompt de l’agent (insensible à la casse)	blog writer

Schéma de réponse (200 OK) :

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Blog Writer",
      "description": "Generates tech articles on a weekly schedule",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * MON",
      "model": "llama-2-70b-chat",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T15:45:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 12,
    "totalPages": 1,
    "currentPage": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

Réponses d’erreur :

400 Bad Request : Paramètres de requête invalides
401 Unauthorized : Clé API invalide
402 Payment Required : Quota API dépassé
404 Not Found : Espace de travail introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents?limit=20&skip=0&status=active&sortBy=createdAt&sortOrder=desc&model=llama-2-70b-chat"

2. Obtenir un agent par ID

Endpoint : GET /agents/{agentId}

Résumé : Obtenir un agent par ID

Description : Récupère la configuration complète et les métadonnées d’un agent unique. Nécessite une authentification via l’en-tête x-api-key et un quota API valide.

Authentification : Requise (x-api-key)

Tags : Agents

Paramètres de chemin :

Paramètre	Type	Description	Exemple
agentId	string	L’ObjectId MongoDB de l’agent à récupérer	507f1f77bcf86cd799439011

Schéma de réponse (200 OK) :

{
  "agent": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439010",
    "name": "Tech Blog Writer",
    "description": "Generates tech articles on a weekly schedule",
    "status": "active",
    "executionMode": "scheduled",
    "schedule": "0 0 * * MON",
    "model": "llama-2-70b-chat",
    "language": "en",
    "prompt": "Write an article about: {topic}",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T15:45:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

Réponses d’erreur :

400 Bad Request : Format d’ID agent invalide
401 Unauthorized : Clé API invalide
402 Payment Required : Quota API dépassé
404 Not Found : Agent ou espace de travail introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011"

3. Lister les articles

Endpoint : GET /articles

Résumé : Lister les articles

Description : Récupère une liste paginée d’articles avec un filtrage avancé par agent, statut, langue, tags et recherche plein texte sur le titre, la description et les mots-clés. Nécessite une authentification via l’en-tête x-api-key et un quota API valide.

Authentification : Requise (x-api-key)

Tags : Articles

Paramètres de requête :

Paramètre	Type	Par défaut	Description	Exemple
skip	number	0	Nombre d’articles à ignorer pour la pagination (offset)	0
limit	number	10	Nombre maximal d’articles à retourner par page (plafonné à 100)	20
sortBy	string	createdAt	Champ utilisé pour trier les articles (ex. : title, createdAt, status, updatedAt)	createdAt
sortOrder	enum	desc	Ordre de tri (croissant ou décroissant)	desc
agentId	string	optional	Filtrer les articles par ID d’agent source (ObjectId MongoDB)	507f1f77bcf86cd799439011
status	enum	optional	Filtrer les articles par statut de publication (draft, published, archived)	published
slug	string	optional	Filtrer les articles par slug donné.	generic-article-slug-as-example
language	string	optional	Filtrer les articles par code langue (ex. : en, tr, de)	en
model	string	optional	Filtrer les articles par modèle LLM utilisé pour la génération	llama-2-70b-chat
tags	string	optional	Filtrer par tags (séparés par des virgules, correspond à n’importe quel tag)	featured,trending,tech
search	string	optional	Recherche plein texte dans le titre, la description, les mots-clés et les tags (insensible à la casse)	artificial intelligence

Schéma de réponse (200 OK) :

{
  "data": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js 14",
      "slug": "getting-started-with-nextjs-14",
      "description": "Learn how to build modern web applications with Next.js 14",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdBy": "507f1f77bcf86cd799439050",
      "updatedBy": "507f1f77bcf86cd799439050",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Réponses d’erreur :

400 Bad Request : Paramètres de requête invalides
401 Unauthorized : Clé API invalide
402 Payment Required : Quota API dépassé
404 Not Found : Espace de travail introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles?limit=25&skip=0&status=published&agentId=507f1f77bcf86cd799439011&language=en&tags=featured,trending&search=artificial+intelligence"

4. Obtenir un article par ID

Endpoint : GET /articles/{articleId}

Résumé : Obtenir un article par ID

Description : Récupère un article unique via son ID, avec contenu complet et blocs structurés. Nécessite une authentification via l’en-tête x-api-key et un quota API valide.

Authentification : Requise (x-api-key)

Tags : Articles

Paramètres de chemin :

Paramètre	Type	Description	Exemple
articleId	string	L’ObjectId MongoDB de l’article à récupérer	607f1f77bcf86cd799439012

Schéma de réponse (200 OK) :

{
  "article": {
    "id": "607f1f77bcf86cd799439012",
    "workspaceId": "507f1f77bcf86cd799439010",
    "agentId": "507f1f77bcf86cd799439011",
    "title": "Getting Started with Next.js 14",
    "slug": "getting-started-with-nextjs-14",
    "description": "Learn how to build modern web applications with Next.js 14",
    "content": "Full article markdown/text content here...",
    "status": "published",
    "language": "en",
    "model": "llama-2-70b-chat",
    "tone": "professional",
    "tags": ["nextjs", "react", "web-development"],
    "blocks": [
      {
        "type": "header",
        "content": "Getting Started with Next.js 14",
        "level": 1
      },
      {
        "type": "text",
        "content": "Next.js 14 introduces new features..."
      },
      {
        "type": "image",
        "url": "https://example.com/image.jpg",
        "caption": "Next.js logo"
      }
    ],
    "meta": {
      "keywords": "nextjs, react, web development",
      "description": "Learn how to build modern web applications with Next.js 14",
      "tags": ["nextjs", "react", "web-development"]
    },
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

Types de blocs :

text : Paragraphe de texte brut

{"type": "text", "content": "Paragraph text"}

header : Titre (niveaux 1 à 6)

{"type": "header", "content": "Heading", "level": 1}

image : Image avec légende optionnelle

{"type": "image", "url": "https://example.com/img.jpg", "caption": "Caption"}

list : Liste ordonnée ou non ordonnée

{"type": "list", "items": ["item1", "item2"], "ordered": false}

code : Bloc de code avec langage

{"type": "code", "content": "const x = 1;", "language": "javascript"}

video : Intégration vidéo

{"type": "video", "url": "https://example.com/video.mp4", "title": "Video title"}

Réponses d’erreur :

400 Bad Request : Format d’ID article invalide
401 Unauthorized : Clé API invalide
402 Payment Required : Quota API dépassé
404 Not Found : Article ou espace de travail introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles/607f1f77bcf86cd799439012"

5. Obtenir les articles d’un agent

Endpoint : GET /agents/{agentId}/articles

Résumé : Obtenir les articles d’un agent spécifique

Description : Récupère tous les articles créés par un agent spécifique, avec filtrage et pagination. Les articles sont renvoyés du plus récent au plus ancien. Nécessite une authentification via l’en-tête x-api-key et un quota API valide.

Authentification : Requise (x-api-key)

Tags : Agents

Paramètres de chemin :

Paramètre	Type	Description	Exemple
agentId	string	L’ObjectId MongoDB de l’agent	507f1f77bcf86cd799439011

Paramètres de requête :

Paramètre	Type	Par défaut	Description	Exemple
limit	number	50	Nombre maximal d’articles à retourner	30
skip	number	0	Nombre d’enregistrements à ignorer pour la pagination	0
status	string	optional	Filtrer par statut d’article (draft, published, archived)	published
sort	string	createdAt	Champ de tri	createdAt
order	enum	desc	Ordre de tri (asc ou desc)	desc
slug	string	optional	Filtrer les articles par slug URL-friendly	getting-started-with-nextjs

Schéma de réponse (200 OK) :

{
  "articles": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js",
      "slug": "getting-started-with-nextjs",
      "description": "A comprehensive guide to Next.js",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 30,
    "totalCount": 45,
    "totalPages": 2,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Réponses d’erreur :

400 Bad Request : Format d’ID agent invalide
401 Unauthorized : Clé API invalide
402 Payment Required : Quota API dépassé
404 Not Found : Agent ou espace de travail introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011/articles?limit=30&skip=0&status=published&sort=createdAt&order=desc"

6. Obtenir les données d’un workspace

Endpoint : GET /workspaces/{workspaceId}

Résumé : Obtenir les données d’un workspace

Description : Récupère les données complètes d’un workspace, y compris ses métadonnées, tous les agents et leurs articles publiés avec contenu complet. Retourne une structure imbriquée agents + articles pour faciliter l’accès aux données du workspace. Nécessite une authentification par clé API correspondant à l’ID du workspace.

Authentification : Requise (x-api-key) - Doit correspondre au workspace demandé

Tags : Workspaces

Paramètres de chemin :

Paramètre	Type	Description	Exemple
workspaceId	string	L’ObjectId MongoDB du workspace à récupérer	507f1f77bcf86cd799439010

Schéma de réponse (200 OK) :

{
  "workspace": {
    "id": "507f1f77bcf86cd799439010",
    "ownerId": "507f1f77bcf86cd799439001",
    "name": "My Content Studio",
    "description": "AI-powered content generation workspace",
    "plan": "pro",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z"
  },
  "agents": [
    {
      "id": "607f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Content Agent",
      "description": "Generates technical articles and tutorials",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * *",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-10T12:00:00Z",
      "updatedAt": "2024-01-20T10:15:00Z",
      "articles": [
        {
          "id": "707f1f77bcf86cd799439012",
          "workspaceId": "507f1f77bcf86cd799439010",
          "agentId": "607f1f77bcf86cd799439011",
          "title": "Getting Started with Next.js",
          "slug": "getting-started-with-nextjs",
          "description": "A comprehensive guide to Next.js",
          "status": "published",
          "language": "en",
          "model": "llama-2-70b-chat",
          "tone": "professional",
          "tags": ["nextjs", "react", "web"],
          "createdAt": "2024-01-10T08:00:00Z",
          "updatedAt": "2024-01-15T12:30:00Z"
        }
      ]
    }
  ]
}

Réponses d’erreur :

400 Bad Request : Format d’ID workspace invalide
401 Unauthorized : Clé API invalide ou workspace non correspondant
402 Payment Required : Quota API dépassé
404 Not Found : Workspace introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/workspaces/507f1f77bcf86cd799439010"

Gestion des erreurs

Tous les endpoints renvoient des réponses d’erreur standardisées avec des codes de statut HTTP :

Format de réponse d’erreur

{
  "error": "Error type",
  "details": "Detailed error message"
}

Codes de statut HTTP

Statut	Description
200	Succès - Requête traitée avec succès
400	Bad Request - Paramètres de requête ou format de chemin invalides
401	Unauthorized - Clé API invalide ou manquante
402	Payment Required - Quota API dépassé pour le plan du workspace
404	Not Found - Ressource inexistante
500	Internal Server Error - Erreur côté serveur

Système de quotas

Chaque workspace dispose d’un quota d’appels API basé sur son plan d’abonnement. Le quota est réinitialisé mensuellement et appliqué à chaque requête.

Limites par plan

Free : 0 appels API/mois
Starter : 0 appels API/mois
Pro : 10,000 appels API/mois
Agency : ~ appels API/mois
Enterprise : Illimité

Application du quota

Chaque requête API compte pour 1 appel sur le quota mensuel. Lorsque le quota est dépassé :

Statut HTTP : 402 Payment Required
Réponse : { error: "API access quota exceeded" }

Formats de réponse

Réponse de succès

Toutes les réponses réussies renvoient un statut 200 avec des données JSON :

{
  "data": [...],
  "pagination": {...}
}

Format de pagination

Tous les endpoints de liste utilisent des métadonnées de pagination cohérentes :

{
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Réponse d’erreur

Toutes les réponses d’erreur incluent les champs error et details :

{
  "error": "Unauthorized",
  "details": "Invalid or missing API key"
}

Résumé des endpoints

Méthode	Endpoint	Description
GET	/agents	Lister les agents avec pagination et filtres
GET	/agents/{agentId}	Obtenir un agent par ID
GET	/articles	Lister les articles avec pagination et filtres avancés
GET	/articles/{articleId}	Obtenir un article par ID avec contenu complet
GET	/agents/{agentId}/articles	Obtenir les articles d’un agent spécifique
GET	/workspaces/{workspaceId}	Obtenir un workspace avec tous les agents et articles
OPTIONS	/*	Support du preflight CORS

Bonnes pratiques

Pagination

Utilisez toujours la pagination pour les endpoints de liste afin d’éviter les timeouts
Commencez avec skip: 0 et limit: 25-50
Utilisez hasNextPage pour déterminer s’il existe plus de résultats
Implémentez un retry avec backoff exponentiel en cas d’échec

Filtrage

Utilisez des filtres spécifiques pour réduire la taille des réponses
Filtrez par status et language pour restreindre les résultats
Utilisez search pour la recherche plein texte au lieu de récupérer tous les enregistrements

Gestion des erreurs

Vérifiez toujours les erreurs 401 (authentification) et 402 (quota)
Implémentez une logique de retry avec backoff exponentiel
Journalisez les détails d’erreur pour le débogage
Traitez les erreurs 4xx comme des erreurs client, et les 5xx comme des erreurs serveur

Performance

Mettez les résultats en cache 5 à 10 minutes pour réduire les appels API
Utilisez limit=50 pour des performances optimales
Combinez les filtres pour minimiser le volume de résultats
Ajustez la taille des lots de pagination selon les limites de quota

Version du document : 2.0 Dernière mise à jour : Janvier 2026 Version API : v1 Statut : Prêt pour la production et la génération de SDK

Documentation API Inkpilots V1

Authentification

Authentification par clé API

Tous les endpoints de l’API V1 nécessitent une authentification via clé API. La clé API doit être transmise dans les en-têtes de la requête.

Format de l’en-tête :

x-api-key: Bearer <your-api-key>

Exemple :

curl -H "x-api-key: Bearer your_api_key_here" https://inkpilots.com/api/v1/agents

Flux de vérification

Le client envoie la requête avec l’en-tête x-api-key
Le serveur appelle la fonction verifyApiKey(apiKeyHeader)
Si la clé est valide, la réponse contient :
- isValid : booléen
- workspaceId : string (ObjectId MongoDB sous forme de chaîne)
Si la clé est invalide, la réponse est { isValid: false }

Réponses d’erreur

401 Unauthorized : Clé API invalide ou manquante, ou permissions insuffisantes
402 Payment Required : Quota d’accès API dépassé pour le plan de l’espace de travail

URL de base et CORS

URL de base

https://inkpilots.com/api/v1

En-têtes CORS

Toutes les réponses incluent les en-têtes CORS suivants :

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, x-api-key

Remarque : CORS autorise toutes les origines car l’API n’utilise pas de cookies (authentification stateless).

Requêtes preflight

Tous les endpoints prennent en charge les requêtes OPTIONS pour le preflight CORS :

curl -X OPTIONS https://inkpilots.com/api/v1/agents

Réponse : 204 No Content avec les en-têtes CORS.

Endpoints API

1. Lister les agents

Endpoint : GET /agents

Résumé : Lister les agents

Authentification : Requise (x-api-key)

Tags : Agents

Paramètres de requête :

Paramètre	Type	Par défaut	Description	Exemple
skip	number	0	Nombre d’agents à ignorer pour la pagination (offset)	0
limit	number	10	Nombre maximal d’agents à retourner par page (plafonné à 100)	20
sortBy	string	createdAt	Champ utilisé pour trier les agents (ex. : name, createdAt, model, isActive)	createdAt
sortOrder	enum	desc	Ordre de tri (croissant ou décroissant)	desc
status	enum	optional	Filtrer les agents par statut (active ou inactive)	active
executionMode	enum	optional	Filtrer les agents par mode d’exécution (scheduled ou batched)	scheduled
model	string	optional	Filtrer les agents par nom de modèle LLM	llama-2-70b-chat
search	string	optional	Recherche plein texte dans le nom et le prompt de l’agent (insensible à la casse)	blog writer

Schéma de réponse (200 OK) :

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Blog Writer",
      "description": "Generates tech articles on a weekly schedule",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * MON",
      "model": "llama-2-70b-chat",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T15:45:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 12,
    "totalPages": 1,
    "currentPage": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

Réponses d’erreur :

400 Bad Request : Paramètres de requête invalides
401 Unauthorized : Clé API invalide
402 Payment Required : Quota API dépassé
404 Not Found : Espace de travail introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents?limit=20&skip=0&status=active&sortBy=createdAt&sortOrder=desc&model=llama-2-70b-chat"

2. Obtenir un agent par ID

Endpoint : GET /agents/{agentId}

Résumé : Obtenir un agent par ID

Description : Récupère la configuration complète et les métadonnées d’un agent unique. Nécessite une authentification via l’en-tête x-api-key et un quota API valide.

Authentification : Requise (x-api-key)

Tags : Agents

Paramètres de chemin :

Paramètre	Type	Description	Exemple
agentId	string	L’ObjectId MongoDB de l’agent à récupérer	507f1f77bcf86cd799439011

Schéma de réponse (200 OK) :

{
  "agent": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439010",
    "name": "Tech Blog Writer",
    "description": "Generates tech articles on a weekly schedule",
    "status": "active",
    "executionMode": "scheduled",
    "schedule": "0 0 * * MON",
    "model": "llama-2-70b-chat",
    "language": "en",
    "prompt": "Write an article about: {topic}",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T15:45:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

Réponses d’erreur :

400 Bad Request : Format d’ID agent invalide
401 Unauthorized : Clé API invalide
402 Payment Required : Quota API dépassé
404 Not Found : Agent ou espace de travail introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011"

3. Lister les articles

Endpoint : GET /articles

Résumé : Lister les articles

Authentification : Requise (x-api-key)

Tags : Articles

Paramètres de requête :

Paramètre	Type	Par défaut	Description	Exemple
skip	number	0	Nombre d’articles à ignorer pour la pagination (offset)	0
limit	number	10	Nombre maximal d’articles à retourner par page (plafonné à 100)	20
sortBy	string	createdAt	Champ utilisé pour trier les articles (ex. : title, createdAt, status, updatedAt)	createdAt
sortOrder	enum	desc	Ordre de tri (croissant ou décroissant)	desc
agentId	string	optional	Filtrer les articles par ID d’agent source (ObjectId MongoDB)	507f1f77bcf86cd799439011
status	enum	optional	Filtrer les articles par statut de publication (draft, published, archived)	published
slug	string	optional	Filtrer les articles par slug donné.	generic-article-slug-as-example
language	string	optional	Filtrer les articles par code langue (ex. : en, tr, de)	en
model	string	optional	Filtrer les articles par modèle LLM utilisé pour la génération	llama-2-70b-chat
tags	string	optional	Filtrer par tags (séparés par des virgules, correspond à n’importe quel tag)	featured,trending,tech
search	string	optional	Recherche plein texte dans le titre, la description, les mots-clés et les tags (insensible à la casse)	artificial intelligence

Schéma de réponse (200 OK) :

{
  "data": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js 14",
      "slug": "getting-started-with-nextjs-14",
      "description": "Learn how to build modern web applications with Next.js 14",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdBy": "507f1f77bcf86cd799439050",
      "updatedBy": "507f1f77bcf86cd799439050",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Réponses d’erreur :

400 Bad Request : Paramètres de requête invalides
401 Unauthorized : Clé API invalide
402 Payment Required : Quota API dépassé
404 Not Found : Espace de travail introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles?limit=25&skip=0&status=published&agentId=507f1f77bcf86cd799439011&language=en&tags=featured,trending&search=artificial+intelligence"

4. Obtenir un article par ID

Endpoint : GET /articles/{articleId}

Résumé : Obtenir un article par ID

Description : Récupère un article unique via son ID, avec contenu complet et blocs structurés. Nécessite une authentification via l’en-tête x-api-key et un quota API valide.

Authentification : Requise (x-api-key)

Tags : Articles

Paramètres de chemin :

Paramètre	Type	Description	Exemple
articleId	string	L’ObjectId MongoDB de l’article à récupérer	607f1f77bcf86cd799439012

Schéma de réponse (200 OK) :

{
  "article": {
    "id": "607f1f77bcf86cd799439012",
    "workspaceId": "507f1f77bcf86cd799439010",
    "agentId": "507f1f77bcf86cd799439011",
    "title": "Getting Started with Next.js 14",
    "slug": "getting-started-with-nextjs-14",
    "description": "Learn how to build modern web applications with Next.js 14",
    "content": "Full article markdown/text content here...",
    "status": "published",
    "language": "en",
    "model": "llama-2-70b-chat",
    "tone": "professional",
    "tags": ["nextjs", "react", "web-development"],
    "blocks": [
      {
        "type": "header",
        "content": "Getting Started with Next.js 14",
        "level": 1
      },
      {
        "type": "text",
        "content": "Next.js 14 introduces new features..."
      },
      {
        "type": "image",
        "url": "https://example.com/image.jpg",
        "caption": "Next.js logo"
      }
    ],
    "meta": {
      "keywords": "nextjs, react, web development",
      "description": "Learn how to build modern web applications with Next.js 14",
      "tags": ["nextjs", "react", "web-development"]
    },
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

Types de blocs :

text : Paragraphe de texte brut

{"type": "text", "content": "Paragraph text"}

header : Titre (niveaux 1 à 6)

{"type": "header", "content": "Heading", "level": 1}

image : Image avec légende optionnelle

{"type": "image", "url": "https://example.com/img.jpg", "caption": "Caption"}

list : Liste ordonnée ou non ordonnée

{"type": "list", "items": ["item1", "item2"], "ordered": false}

code : Bloc de code avec langage

{"type": "code", "content": "const x = 1;", "language": "javascript"}

video : Intégration vidéo

{"type": "video", "url": "https://example.com/video.mp4", "title": "Video title"}

Réponses d’erreur :

400 Bad Request : Format d’ID article invalide
401 Unauthorized : Clé API invalide
402 Payment Required : Quota API dépassé
404 Not Found : Article ou espace de travail introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles/607f1f77bcf86cd799439012"

5. Obtenir les articles d’un agent

Endpoint : GET /agents/{agentId}/articles

Résumé : Obtenir les articles d’un agent spécifique

Authentification : Requise (x-api-key)

Tags : Agents

Paramètres de chemin :

Paramètre	Type	Description	Exemple
agentId	string	L’ObjectId MongoDB de l’agent	507f1f77bcf86cd799439011

Paramètres de requête :

Paramètre	Type	Par défaut	Description	Exemple
limit	number	50	Nombre maximal d’articles à retourner	30
skip	number	0	Nombre d’enregistrements à ignorer pour la pagination	0
status	string	optional	Filtrer par statut d’article (draft, published, archived)	published
sort	string	createdAt	Champ de tri	createdAt
order	enum	desc	Ordre de tri (asc ou desc)	desc
slug	string	optional	Filtrer les articles par slug URL-friendly	getting-started-with-nextjs

Schéma de réponse (200 OK) :

{
  "articles": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js",
      "slug": "getting-started-with-nextjs",
      "description": "A comprehensive guide to Next.js",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 30,
    "totalCount": 45,
    "totalPages": 2,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Réponses d’erreur :

400 Bad Request : Format d’ID agent invalide
401 Unauthorized : Clé API invalide
402 Payment Required : Quota API dépassé
404 Not Found : Agent ou espace de travail introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011/articles?limit=30&skip=0&status=published&sort=createdAt&order=desc"

6. Obtenir les données d’un workspace

Endpoint : GET /workspaces/{workspaceId}

Résumé : Obtenir les données d’un workspace

Authentification : Requise (x-api-key) - Doit correspondre au workspace demandé

Tags : Workspaces

Paramètres de chemin :

Paramètre	Type	Description	Exemple
workspaceId	string	L’ObjectId MongoDB du workspace à récupérer	507f1f77bcf86cd799439010

Schéma de réponse (200 OK) :

{
  "workspace": {
    "id": "507f1f77bcf86cd799439010",
    "ownerId": "507f1f77bcf86cd799439001",
    "name": "My Content Studio",
    "description": "AI-powered content generation workspace",
    "plan": "pro",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z"
  },
  "agents": [
    {
      "id": "607f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Content Agent",
      "description": "Generates technical articles and tutorials",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * *",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-10T12:00:00Z",
      "updatedAt": "2024-01-20T10:15:00Z",
      "articles": [
        {
          "id": "707f1f77bcf86cd799439012",
          "workspaceId": "507f1f77bcf86cd799439010",
          "agentId": "607f1f77bcf86cd799439011",
          "title": "Getting Started with Next.js",
          "slug": "getting-started-with-nextjs",
          "description": "A comprehensive guide to Next.js",
          "status": "published",
          "language": "en",
          "model": "llama-2-70b-chat",
          "tone": "professional",
          "tags": ["nextjs", "react", "web"],
          "createdAt": "2024-01-10T08:00:00Z",
          "updatedAt": "2024-01-15T12:30:00Z"
        }
      ]
    }
  ]
}

Réponses d’erreur :

400 Bad Request : Format d’ID workspace invalide
401 Unauthorized : Clé API invalide ou workspace non correspondant
402 Payment Required : Quota API dépassé
404 Not Found : Workspace introuvable
500 Internal Server Error : Erreur serveur

Exemple de requête :

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/workspaces/507f1f77bcf86cd799439010"

Gestion des erreurs

Tous les endpoints renvoient des réponses d’erreur standardisées avec des codes de statut HTTP :

Format de réponse d’erreur

{
  "error": "Error type",
  "details": "Detailed error message"
}

Codes de statut HTTP

Statut	Description
200	Succès - Requête traitée avec succès
400	Bad Request - Paramètres de requête ou format de chemin invalides
401	Unauthorized - Clé API invalide ou manquante
402	Payment Required - Quota API dépassé pour le plan du workspace
404	Not Found - Ressource inexistante
500	Internal Server Error - Erreur côté serveur

Système de quotas

Chaque workspace dispose d’un quota d’appels API basé sur son plan d’abonnement. Le quota est réinitialisé mensuellement et appliqué à chaque requête.

Limites par plan

Free : 0 appels API/mois
Starter : 0 appels API/mois
Pro : 10,000 appels API/mois
Agency : ~ appels API/mois
Enterprise : Illimité

Application du quota

Chaque requête API compte pour 1 appel sur le quota mensuel. Lorsque le quota est dépassé :

Statut HTTP : 402 Payment Required
Réponse : { error: "API access quota exceeded" }

Formats de réponse

Réponse de succès

Toutes les réponses réussies renvoient un statut 200 avec des données JSON :

{
  "data": [...],
  "pagination": {...}
}

Format de pagination

Tous les endpoints de liste utilisent des métadonnées de pagination cohérentes :

{
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Réponse d’erreur

Toutes les réponses d’erreur incluent les champs error et details :

{
  "error": "Unauthorized",
  "details": "Invalid or missing API key"
}

Résumé des endpoints

Méthode	Endpoint	Description
GET	/agents	Lister les agents avec pagination et filtres
GET	/agents/{agentId}	Obtenir un agent par ID
GET	/articles	Lister les articles avec pagination et filtres avancés
GET	/articles/{articleId}	Obtenir un article par ID avec contenu complet
GET	/agents/{agentId}/articles	Obtenir les articles d’un agent spécifique
GET	/workspaces/{workspaceId}	Obtenir un workspace avec tous les agents et articles
OPTIONS	/*	Support du preflight CORS

Bonnes pratiques

Pagination

Utilisez toujours la pagination pour les endpoints de liste afin d’éviter les timeouts
Commencez avec skip: 0 et limit: 25-50
Utilisez hasNextPage pour déterminer s’il existe plus de résultats
Implémentez un retry avec backoff exponentiel en cas d’échec

Filtrage

Utilisez des filtres spécifiques pour réduire la taille des réponses
Filtrez par status et language pour restreindre les résultats
Utilisez search pour la recherche plein texte au lieu de récupérer tous les enregistrements

Gestion des erreurs

Vérifiez toujours les erreurs 401 (authentification) et 402 (quota)
Implémentez une logique de retry avec backoff exponentiel
Journalisez les détails d’erreur pour le débogage
Traitez les erreurs 4xx comme des erreurs client, et les 5xx comme des erreurs serveur

Performance

Mettez les résultats en cache 5 à 10 minutes pour réduire les appels API
Utilisez limit=50 pour des performances optimales
Combinez les filtres pour minimiser le volume de résultats
Ajustez la taille des lots de pagination selon les limites de quota

Version du document : 2.0 Dernière mise à jour : Janvier 2026 Version API : v1 Statut : Prêt pour la production et la génération de SDK