Documentación de la API V1 de Inkpilots

Propósito: Referencia completa de la API pública V1 con descripciones detalladas de endpoints, parámetros de consulta, autenticación, formatos de respuesta y sistema de cuotas para la generación del SDK de Node.js.

Tabla de Contenidos

Autenticación
URL Base y CORS
Endpoints de la API
Manejo de Errores
Sistema de Cuotas
Formatos de Respuesta
Resumen de Endpoints

Autenticación

Autenticación con Clave API

Todos los endpoints de la API V1 requieren autenticación mediante clave API. La clave API se envía en el encabezado de la solicitud.

Formato del Encabezado:

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

Ejemplo:

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

Flujo de Verificación

El cliente envía la solicitud con el encabezado x-api-key
El servidor llama a la función verifyApiKey(apiKeyHeader)
Si es válida, devuelve:
- isValid: boolean
- workspaceId: string (ObjectId de MongoDB como string)
Si no es válida, devuelve { isValid: false }

Respuestas de Error

401 Unauthorized: Clave API inválida o faltante, o permisos insuficientes
402 Payment Required: Se superó la cuota de acceso API del plan del workspace

URL Base y CORS

URL Base

https://inkpilots.com/api/v1

Encabezados CORS

Todas las respuestas incluyen los siguientes encabezados CORS:

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

Nota: CORS permite todos los orígenes porque la API no usa cookies (autenticación sin estado).

Solicitudes Preflight

Todos los endpoints soportan solicitudes OPTIONS para preflight de CORS:

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

Respuesta: 204 No Content con encabezados CORS.

Endpoints de la API

1. Listar Agentes

Endpoint: GET /agents

Resumen: Listar agentes

Descripción: Obtiene una lista paginada de agentes con filtros avanzados por estado, modo de ejecución, modelo LLM y búsqueda de texto completo en nombre y prompt. Requiere autenticación mediante encabezado x-api-key y cuota API válida.

Autenticación: Requerida (x-api-key)

Etiquetas: Agents

Parámetros de Consulta:

Parámetro	Tipo	Predeterminado	Descripción	Ejemplo
skip	number	0	Cantidad de agentes a omitir para paginación (offset)	0
limit	number	10	Cantidad máxima de agentes por página (límite: 100)	20
sortBy	string	createdAt	Campo para ordenar agentes (ej.: name, createdAt, model, isActive)	createdAt
sortOrder	enum	desc	Dirección del ordenamiento (ascendente o descendente)	desc
status	enum	optional	Filtrar agentes por estado (active o inactive)	active
executionMode	enum	optional	Filtrar agentes por modo de ejecución (scheduled o batched)	scheduled
model	string	optional	Filtrar agentes por nombre del modelo LLM	llama-2-70b-chat
search	string	optional	Búsqueda de texto completo en nombre y prompt del agente (no sensible a mayúsculas)	blog writer

Esquema de Respuesta (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
  }
}

Respuestas de Error:

400 Bad Request: Parámetros de consulta inválidos
401 Unauthorized: Clave API inválida
402 Payment Required: Cuota API excedida
404 Not Found: Workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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. Obtener Agente por ID

Endpoint: GET /agents/{agentId}

Resumen: Obtener agente por ID

Descripción: Obtiene la configuración completa y metadatos de un agente. Requiere autenticación mediante encabezado x-api-key y cuota API válida.

Autenticación: Requerida (x-api-key)

Etiquetas: Agents

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
agentId	string	ObjectId de MongoDB del agente a obtener	507f1f77bcf86cd799439011

Esquema de Respuesta (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"
  }
}

Respuestas de Error:

400 Bad Request: Formato de ID de agente inválido
401 Unauthorized: Clave API inválida
402 Payment Required: Cuota API excedida
404 Not Found: Agente o workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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

3. Listar Artículos

Endpoint: GET /articles

Resumen: Listar artículos

Descripción: Obtiene una lista paginada de artículos con filtros avanzados por agente, estado, idioma, etiquetas y búsqueda de texto completo en título, descripción y palabras clave. Requiere autenticación mediante encabezado x-api-key y cuota API válida.

Autenticación: Requerida (x-api-key)

Etiquetas: Articles

Parámetros de Consulta:

Parámetro	Tipo	Predeterminado	Descripción	Ejemplo
skip	number	0	Cantidad de artículos a omitir para paginación (offset)	0
limit	number	10	Cantidad máxima de artículos por página (límite: 100)	20
sortBy	string	createdAt	Campo para ordenar artículos (ej.: title, createdAt, status, updatedAt)	createdAt
sortOrder	enum	desc	Dirección del ordenamiento (ascendente o descendente)	desc
agentId	string	optional	Filtrar artículos por ID del agente origen (ObjectId de MongoDB)	507f1f77bcf86cd799439011
status	enum	optional	Filtrar artículos por estado de publicación (draft, published, archived)	published
slug	string	optional	Filtrar artículos por slug específico.	generic-article-slug-as-example
language	string	optional	Filtrar artículos por código de idioma (ej.: en, tr, de)	en
model	string	optional	Filtrar artículos por modelo LLM usado en la generación	llama-2-70b-chat
tags	string	optional	Filtrar por etiquetas (separadas por comas, coincide cualquier etiqueta)	featured,trending,tech
search	string	optional	Búsqueda de texto completo en título, descripción, palabras clave y etiquetas (no sensible a mayúsculas)	artificial intelligence

Esquema de Respuesta (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
  }
}

Respuestas de Error:

400 Bad Request: Parámetros de consulta inválidos
401 Unauthorized: Clave API inválida
402 Payment Required: Cuota API excedida
404 Not Found: Workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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. Obtener Artículo por ID

Endpoint: GET /articles/{articleId}

Resumen: Obtener artículo por ID

Descripción: Obtiene un artículo por su ID con contenido completo y bloques estructurados. Requiere autenticación mediante encabezado x-api-key y cuota API válida.

Autenticación: Requerida (x-api-key)

Etiquetas: Articles

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
articleId	string	ObjectId de MongoDB del artículo a obtener	607f1f77bcf86cd799439012

Esquema de Respuesta (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"
  }
}

Tipos de Bloque:

text: Párrafo de texto plano

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

header: Encabezado (niveles 1-6)

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

image: Imagen con subtítulo opcional

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

list: Lista ordenada o desordenada

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

code: Bloque de código con lenguaje

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

video: Inserción de video

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

Respuestas de Error:

400 Bad Request: Formato de ID de artículo inválido
401 Unauthorized: Clave API inválida
402 Payment Required: Cuota API excedida
404 Not Found: Artículo o workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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

5. Obtener Artículos de un Agente

Endpoint: GET /agents/{agentId}/articles

Resumen: Obtener artículos de un agente específico

Descripción: Obtiene todos los artículos creados por un agente específico con filtros y paginación. Devuelve los artículos ordenados del más nuevo al más antiguo. Requiere autenticación mediante encabezado x-api-key y cuota API válida.

Autenticación: Requerida (x-api-key)

Etiquetas: Agents

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
agentId	string	ObjectId de MongoDB del agente	507f1f77bcf86cd799439011

Parámetros de Consulta:

Parámetro	Tipo	Predeterminado	Descripción	Ejemplo
limit	number	50	Cantidad máxima de artículos a devolver	30
skip	number	0	Cantidad de registros a omitir para paginación	0
status	string	optional	Filtrar por estado del artículo (draft, published, archived)	published
sort	string	createdAt	Campo para ordenar	createdAt
order	enum	desc	Dirección del ordenamiento (asc o desc)	desc
slug	string	optional	Filtrar artículos por slug amigable para URL	getting-started-with-nextjs

Esquema de Respuesta (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
  }
}

Respuestas de Error:

400 Bad Request: Formato de ID de agente inválido
401 Unauthorized: Clave API inválida
402 Payment Required: Cuota API excedida
404 Not Found: Agente o workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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. Obtener Datos del Workspace

Endpoint: GET /workspaces/{workspaceId}

Resumen: Obtener datos del workspace

Descripción: Obtiene los datos completos del workspace, incluidos metadatos del workspace, todos los agentes y sus artículos publicados con contenido completo. Devuelve agentes anidados con artículos para facilitar el acceso a la estructura de contenido del workspace. Requiere autenticación por clave API que coincida con el ID del workspace.

Autenticación: Requerida (x-api-key) - Debe coincidir con el workspace accedido

Etiquetas: Workspaces

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
workspaceId	string	ObjectId de MongoDB del workspace a obtener	507f1f77bcf86cd799439010

Esquema de Respuesta (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"
        }
      ]
    }
  ]
}

Respuestas de Error:

400 Bad Request: Formato de ID de workspace inválido
401 Unauthorized: Clave API inválida o workspace no coincide
402 Payment Required: Cuota API excedida
404 Not Found: Workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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

Manejo de Errores

Todos los endpoints devuelven respuestas de error estandarizadas con códigos de estado HTTP:

Formato de Respuesta de Error

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

Códigos de Estado HTTP

Estado	Descripción
200	Éxito - La solicitud se completó correctamente
400	Bad Request - Parámetros de consulta o formato de ruta inválidos
401	Unauthorized - Clave API inválida o faltante
402	Payment Required - Cuota API excedida para el plan del workspace
404	Not Found - El recurso no existe
500	Internal Server Error - Ocurrió un error del lado del servidor

Sistema de Cuotas

Cada workspace tiene una cuota de llamadas API basada en su plan de suscripción. La cuota se reinicia mensualmente y se aplica en cada solicitud.

Límites por Plan

Free: 0 llamadas API/mes
Starter: 0 llamadas API/mes
Pro: 10,000 llamadas API/mes
Agency: ~ llamadas API/mes
Enterprise: Ilimitado

Aplicación de Cuota

Cada solicitud API cuenta como 1 llamada para la cuota mensual. Cuando se excede la cuota:

Estado HTTP: 402 Payment Required
Respuesta: { error: "API access quota exceeded" }

Formatos de Respuesta

Respuesta Exitosa

Todas las respuestas exitosas devuelven código 200 con datos JSON:

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

Formato de Paginación

Todos los endpoints de listado usan metadatos de paginación consistentes:

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

Respuesta de Error

Todas las respuestas de error incluyen los campos error y details:

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

Resumen de Endpoints

Método	Endpoint	Descripción
GET	/agents	Lista agentes con paginación y filtros
GET	/agents/{agentId}	Obtiene un agente por ID
GET	/articles	Lista artículos con paginación y filtros avanzados
GET	/articles/{articleId}	Obtiene un artículo por ID con contenido completo
GET	/agents/{agentId}/articles	Obtiene artículos de un agente específico
GET	/workspaces/{workspaceId}	Obtiene un workspace con todos sus agentes y artículos
OPTIONS	/*	Soporte de preflight CORS

Buenas Prácticas

Paginación

Usa siempre paginación en endpoints de listado para evitar timeouts
Comienza con skip: 0 y limit: 25-50
Usa hasNextPage para determinar si existen más resultados
Implementa backoff exponencial para solicitudes fallidas

Filtrado

Usa filtros específicos para reducir el tamaño de la respuesta
Filtra por status e language para acotar resultados
Usa search para búsquedas de texto completo en lugar de traer todos los registros

Manejo de Errores

Revisa siempre errores 401 (autenticación) y 402 (cuota)
Implementa lógica de reintento con backoff exponencial
Registra detalles de error para depuración
Trata errores 4xx como problemas de cliente y 5xx como problemas de servidor

Rendimiento

Almacena resultados en caché por 5-10 minutos para reducir llamadas API
Usa limit=50 para rendimiento óptimo
Combina filtros para minimizar el conjunto de resultados
Considera el tamaño de lote de paginación según los límites de cuota

Versión del Documento: 2.0 Última Actualización: Enero 2026 Versión de la API: v1 Estado: Lista para producción para generación de SDK

Documentación de la API V1 de Inkpilots

Autenticación

Autenticación con Clave API

Todos los endpoints de la API V1 requieren autenticación mediante clave API. La clave API se envía en el encabezado de la solicitud.

Formato del Encabezado:

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

Ejemplo:

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

Flujo de Verificación

El cliente envía la solicitud con el encabezado x-api-key
El servidor llama a la función verifyApiKey(apiKeyHeader)
Si es válida, devuelve:
- isValid: boolean
- workspaceId: string (ObjectId de MongoDB como string)
Si no es válida, devuelve { isValid: false }

Respuestas de Error

401 Unauthorized: Clave API inválida o faltante, o permisos insuficientes
402 Payment Required: Se superó la cuota de acceso API del plan del workspace

URL Base y CORS

URL Base

https://inkpilots.com/api/v1

Encabezados CORS

Todas las respuestas incluyen los siguientes encabezados CORS:

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

Nota: CORS permite todos los orígenes porque la API no usa cookies (autenticación sin estado).

Solicitudes Preflight

Todos los endpoints soportan solicitudes OPTIONS para preflight de CORS:

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

Respuesta: 204 No Content con encabezados CORS.

Endpoints de la API

1. Listar Agentes

Endpoint: GET /agents

Resumen: Listar agentes

Autenticación: Requerida (x-api-key)

Etiquetas: Agents

Parámetros de Consulta:

Parámetro	Tipo	Predeterminado	Descripción	Ejemplo
skip	number	0	Cantidad de agentes a omitir para paginación (offset)	0
limit	number	10	Cantidad máxima de agentes por página (límite: 100)	20
sortBy	string	createdAt	Campo para ordenar agentes (ej.: name, createdAt, model, isActive)	createdAt
sortOrder	enum	desc	Dirección del ordenamiento (ascendente o descendente)	desc
status	enum	optional	Filtrar agentes por estado (active o inactive)	active
executionMode	enum	optional	Filtrar agentes por modo de ejecución (scheduled o batched)	scheduled
model	string	optional	Filtrar agentes por nombre del modelo LLM	llama-2-70b-chat
search	string	optional	Búsqueda de texto completo en nombre y prompt del agente (no sensible a mayúsculas)	blog writer

Esquema de Respuesta (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
  }
}

Respuestas de Error:

400 Bad Request: Parámetros de consulta inválidos
401 Unauthorized: Clave API inválida
402 Payment Required: Cuota API excedida
404 Not Found: Workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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. Obtener Agente por ID

Endpoint: GET /agents/{agentId}

Resumen: Obtener agente por ID

Descripción: Obtiene la configuración completa y metadatos de un agente. Requiere autenticación mediante encabezado x-api-key y cuota API válida.

Autenticación: Requerida (x-api-key)

Etiquetas: Agents

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
agentId	string	ObjectId de MongoDB del agente a obtener	507f1f77bcf86cd799439011

Esquema de Respuesta (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"
  }
}

Respuestas de Error:

400 Bad Request: Formato de ID de agente inválido
401 Unauthorized: Clave API inválida
402 Payment Required: Cuota API excedida
404 Not Found: Agente o workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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

3. Listar Artículos

Endpoint: GET /articles

Resumen: Listar artículos

Autenticación: Requerida (x-api-key)

Etiquetas: Articles

Parámetros de Consulta:

Parámetro	Tipo	Predeterminado	Descripción	Ejemplo
skip	number	0	Cantidad de artículos a omitir para paginación (offset)	0
limit	number	10	Cantidad máxima de artículos por página (límite: 100)	20
sortBy	string	createdAt	Campo para ordenar artículos (ej.: title, createdAt, status, updatedAt)	createdAt
sortOrder	enum	desc	Dirección del ordenamiento (ascendente o descendente)	desc
agentId	string	optional	Filtrar artículos por ID del agente origen (ObjectId de MongoDB)	507f1f77bcf86cd799439011
status	enum	optional	Filtrar artículos por estado de publicación (draft, published, archived)	published
slug	string	optional	Filtrar artículos por slug específico.	generic-article-slug-as-example
language	string	optional	Filtrar artículos por código de idioma (ej.: en, tr, de)	en
model	string	optional	Filtrar artículos por modelo LLM usado en la generación	llama-2-70b-chat
tags	string	optional	Filtrar por etiquetas (separadas por comas, coincide cualquier etiqueta)	featured,trending,tech
search	string	optional	Búsqueda de texto completo en título, descripción, palabras clave y etiquetas (no sensible a mayúsculas)	artificial intelligence

Esquema de Respuesta (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
  }
}

Respuestas de Error:

400 Bad Request: Parámetros de consulta inválidos
401 Unauthorized: Clave API inválida
402 Payment Required: Cuota API excedida
404 Not Found: Workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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. Obtener Artículo por ID

Endpoint: GET /articles/{articleId}

Resumen: Obtener artículo por ID

Descripción: Obtiene un artículo por su ID con contenido completo y bloques estructurados. Requiere autenticación mediante encabezado x-api-key y cuota API válida.

Autenticación: Requerida (x-api-key)

Etiquetas: Articles

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
articleId	string	ObjectId de MongoDB del artículo a obtener	607f1f77bcf86cd799439012

Esquema de Respuesta (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"
  }
}

Tipos de Bloque:

text: Párrafo de texto plano

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

header: Encabezado (niveles 1-6)

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

image: Imagen con subtítulo opcional

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

list: Lista ordenada o desordenada

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

code: Bloque de código con lenguaje

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

video: Inserción de video

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

Respuestas de Error:

400 Bad Request: Formato de ID de artículo inválido
401 Unauthorized: Clave API inválida
402 Payment Required: Cuota API excedida
404 Not Found: Artículo o workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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

5. Obtener Artículos de un Agente

Endpoint: GET /agents/{agentId}/articles

Resumen: Obtener artículos de un agente específico

Autenticación: Requerida (x-api-key)

Etiquetas: Agents

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
agentId	string	ObjectId de MongoDB del agente	507f1f77bcf86cd799439011

Parámetros de Consulta:

Parámetro	Tipo	Predeterminado	Descripción	Ejemplo
limit	number	50	Cantidad máxima de artículos a devolver	30
skip	number	0	Cantidad de registros a omitir para paginación	0
status	string	optional	Filtrar por estado del artículo (draft, published, archived)	published
sort	string	createdAt	Campo para ordenar	createdAt
order	enum	desc	Dirección del ordenamiento (asc o desc)	desc
slug	string	optional	Filtrar artículos por slug amigable para URL	getting-started-with-nextjs

Esquema de Respuesta (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
  }
}

Respuestas de Error:

400 Bad Request: Formato de ID de agente inválido
401 Unauthorized: Clave API inválida
402 Payment Required: Cuota API excedida
404 Not Found: Agente o workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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. Obtener Datos del Workspace

Endpoint: GET /workspaces/{workspaceId}

Resumen: Obtener datos del workspace

Autenticación: Requerida (x-api-key) - Debe coincidir con el workspace accedido

Etiquetas: Workspaces

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
workspaceId	string	ObjectId de MongoDB del workspace a obtener	507f1f77bcf86cd799439010

Esquema de Respuesta (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"
        }
      ]
    }
  ]
}

Respuestas de Error:

400 Bad Request: Formato de ID de workspace inválido
401 Unauthorized: Clave API inválida o workspace no coincide
402 Payment Required: Cuota API excedida
404 Not Found: Workspace no encontrado
500 Internal Server Error: Error del servidor

Ejemplo de Solicitud:

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

Manejo de Errores

Todos los endpoints devuelven respuestas de error estandarizadas con códigos de estado HTTP:

Formato de Respuesta de Error

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

Códigos de Estado HTTP

Estado	Descripción
200	Éxito - La solicitud se completó correctamente
400	Bad Request - Parámetros de consulta o formato de ruta inválidos
401	Unauthorized - Clave API inválida o faltante
402	Payment Required - Cuota API excedida para el plan del workspace
404	Not Found - El recurso no existe
500	Internal Server Error - Ocurrió un error del lado del servidor

Sistema de Cuotas

Cada workspace tiene una cuota de llamadas API basada en su plan de suscripción. La cuota se reinicia mensualmente y se aplica en cada solicitud.

Límites por Plan

Free: 0 llamadas API/mes
Starter: 0 llamadas API/mes
Pro: 10,000 llamadas API/mes
Agency: ~ llamadas API/mes
Enterprise: Ilimitado

Aplicación de Cuota

Cada solicitud API cuenta como 1 llamada para la cuota mensual. Cuando se excede la cuota:

Estado HTTP: 402 Payment Required
Respuesta: { error: "API access quota exceeded" }

Formatos de Respuesta

Respuesta Exitosa

Todas las respuestas exitosas devuelven código 200 con datos JSON:

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

Formato de Paginación

Todos los endpoints de listado usan metadatos de paginación consistentes:

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

Respuesta de Error

Todas las respuestas de error incluyen los campos error y details:

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

Resumen de Endpoints

Método	Endpoint	Descripción
GET	/agents	Lista agentes con paginación y filtros
GET	/agents/{agentId}	Obtiene un agente por ID
GET	/articles	Lista artículos con paginación y filtros avanzados
GET	/articles/{articleId}	Obtiene un artículo por ID con contenido completo
GET	/agents/{agentId}/articles	Obtiene artículos de un agente específico
GET	/workspaces/{workspaceId}	Obtiene un workspace con todos sus agentes y artículos
OPTIONS	/*	Soporte de preflight CORS

Buenas Prácticas

Paginación

Usa siempre paginación en endpoints de listado para evitar timeouts
Comienza con skip: 0 y limit: 25-50
Usa hasNextPage para determinar si existen más resultados
Implementa backoff exponencial para solicitudes fallidas

Filtrado

Usa filtros específicos para reducir el tamaño de la respuesta
Filtra por status e language para acotar resultados
Usa search para búsquedas de texto completo en lugar de traer todos los registros

Manejo de Errores

Revisa siempre errores 401 (autenticación) y 402 (cuota)
Implementa lógica de reintento con backoff exponencial
Registra detalles de error para depuración
Trata errores 4xx como problemas de cliente y 5xx como problemas de servidor

Rendimiento

Almacena resultados en caché por 5-10 minutos para reducir llamadas API
Usa limit=50 para rendimiento óptimo
Combina filtros para minimizar el conjunto de resultados
Considera el tamaño de lote de paginación según los límites de cuota

Versión del Documento: 2.0 Última Actualización: Enero 2026 Versión de la API: v1 Estado: Lista para producción para generación de SDK