InkpilotsInkpilotsInkpilots
AnmeldenLoslegen
ÜberblickEndpunkteSDK

Inkpilots V1 API-Dokumentation

Zweck: Vollständige API-Referenz für die öffentliche V1-API mit umfassenden Endpoint-Beschreibungen, Query-Parametern, Authentifizierung, Antwortformaten und Quotensystem für die Node.js-SDK-Generierung.

Inhaltsverzeichnis

  1. Authentifizierung
  2. Basis-URL & CORS
  3. API-Endpunkte
  4. Fehlerbehandlung
  5. Quotensystem
  6. Antwortformate
  7. Endpoint-Übersicht

Authentifizierung

API-Key-Authentifizierung

Alle V1-API-Endpunkte erfordern Authentifizierung per API-Key. Der API-Key wird im Request-Header übergeben.

Header-Format:

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

Beispiel:

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

Verifizierungsablauf

  1. Der Client sendet eine Anfrage mit dem Header x-api-key
  2. Der Server ruft die Funktion verifyApiKey(apiKeyHeader) auf
  3. Falls gültig, Rückgabe:
    • isValid: boolean
    • workspaceId: string (MongoDB ObjectId als String)
  4. Falls ungültig, Rückgabe { isValid: false }

Fehlerantworten

  • 401 Unauthorized: Ungültiger oder fehlender API-Key oder unzureichende Berechtigungen
  • 402 Payment Required: API-Zugriffsquote für den Plan des Workspace überschritten

Basis-URL & CORS

Basis-URL

https://inkpilots.com/api/v1

CORS-Header

Alle Antworten enthalten die folgenden CORS-Header:

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

Hinweis: CORS erlaubt alle Origins, da die API keine Cookies verwendet (zustandslose Authentifizierung).

Preflight-Anfragen

Alle Endpunkte unterstützen OPTIONS-Anfragen für CORS-Preflight:

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

Antwort: 204 No Content mit CORS-Headern.

API-Endpunkte

1. Agents auflisten

Endpunkt: GET /agents

Kurzbeschreibung: Agents auflisten

Beschreibung: Ruft eine paginierte Liste von Agents mit erweiterten Filtern nach Status, Ausführungsmodus, LLM-Modell und Volltextsuche über Name und Prompt ab. Erfordert Authentifizierung über den x-api-key-Header sowie eine gültige API-Quote.

Authentifizierung: Erforderlich (x-api-key)

Tags: Agents

Query-Parameter:

ParameterTypStandardBeschreibungBeispiel
skipnumber0Anzahl der zu überspringenden Agents für Pagination (Offset)0
limitnumber10Maximale Anzahl zurückzugebender Agents pro Seite (auf 100 begrenzt)20
sortBystringcreatedAtFeld, nach dem sortiert wird (z. B. name, createdAt, model, isActive)createdAt
sortOrderenumdescSortierrichtung (aufsteigend oder absteigend)desc
statusenumoptionalFiltert Agents nach Status (active oder inactive)active
executionModeenumoptionalFiltert Agents nach Ausführungsmodus (scheduled oder batched)scheduled
modelstringoptionalFiltert Agents nach LLM-Modellnamellama-2-70b-chat
searchstringoptionalVolltextsuche in Agent-Name und Prompt (ohne Groß-/Kleinschreibung)blog writer

Antwortschema (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
  }
}

Fehlerantworten:

  • 400 Bad Request: Ungültige Query-Parameter
  • 401 Unauthorized: Ungültiger API-Key
  • 402 Payment Required: API-Quote überschritten
  • 404 Not Found: Workspace nicht gefunden
  • 500 Internal Server Error: Serverfehler

Beispielanfrage:

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. Agent per ID abrufen

Endpunkt: GET /agents/{agentId}

Kurzbeschreibung: Agent per ID abrufen

Beschreibung: Ruft die vollständige Konfiguration und Metadaten eines einzelnen Agents ab. Erfordert Authentifizierung über den x-api-key-Header sowie eine gültige API-Quote.

Authentifizierung: Erforderlich (x-api-key)

Tags: Agents

Pfadparameter:

ParameterTypBeschreibungBeispiel
agentIdstringDie MongoDB-ObjectId des abzurufenden Agents507f1f77bcf86cd799439011

Antwortschema (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"
  }
}

Fehlerantworten:

  • 400 Bad Request: Ungültiges Agent-ID-Format
  • 401 Unauthorized: Ungültiger API-Key
  • 402 Payment Required: API-Quote überschritten
  • 404 Not Found: Agent oder Workspace nicht gefunden
  • 500 Internal Server Error: Serverfehler

Beispielanfrage:

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

3. Artikel auflisten

Endpunkt: GET /articles

Kurzbeschreibung: Artikel auflisten

Beschreibung: Ruft eine paginierte Liste von Artikeln mit erweiterten Filtern nach Agent, Status, Sprache, Tags und Volltextsuche über Titel, Beschreibung und Keywords ab. Erfordert Authentifizierung über den x-api-key-Header sowie eine gültige API-Quote.

Authentifizierung: Erforderlich (x-api-key)

Tags: Articles

Query-Parameter:

ParameterTypStandardBeschreibungBeispiel
skipnumber0Anzahl der zu überspringenden Artikel für Pagination (Offset)0
limitnumber10Maximale Anzahl zurückzugebender Artikel pro Seite (auf 100 begrenzt)20
sortBystringcreatedAtFeld, nach dem sortiert wird (z. B. title, createdAt, status, updatedAt)createdAt
sortOrderenumdescSortierrichtung (aufsteigend oder absteigend)desc
agentIdstringoptionalFiltert Artikel nach Quell-Agent-ID (MongoDB ObjectId)507f1f77bcf86cd799439011
statusenumoptionalFiltert Artikel nach Veröffentlichungsstatus (draft, published, archived)published
slugstringoptionalFiltert Artikel nach dem angegebenen Slug.generic-article-slug-as-example
languagestringoptionalFiltert Artikel nach Sprachcode (z. B. en, tr, de)en
modelstringoptionalFiltert Artikel nach dem für die Generierung verwendeten LLM-Modellllama-2-70b-chat
tagsstringoptionalFiltert nach Tags (kommagetrennt, Treffer bei beliebigem Tag)featured,trending,tech
searchstringoptionalVolltextsuche in Titel, Beschreibung, Keywords und Tags (ohne Groß-/Kleinschreibung)artificial intelligence

Antwortschema (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
  }
}

Fehlerantworten:

  • 400 Bad Request: Ungültige Query-Parameter
  • 401 Unauthorized: Ungültiger API-Key
  • 402 Payment Required: API-Quote überschritten
  • 404 Not Found: Workspace nicht gefunden
  • 500 Internal Server Error: Serverfehler

Beispielanfrage:

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. Artikel per ID abrufen

Endpunkt: GET /articles/{articleId}

Kurzbeschreibung: Artikel per ID abrufen

Beschreibung: Ruft einen einzelnen Artikel per ID mit vollständigem Inhalt und strukturierten Blöcken ab. Erfordert Authentifizierung über den x-api-key-Header sowie eine gültige API-Quote.

Authentifizierung: Erforderlich (x-api-key)

Tags: Articles

Pfadparameter:

ParameterTypBeschreibungBeispiel
articleIdstringDie MongoDB-ObjectId des abzurufenden Artikels607f1f77bcf86cd799439012

Antwortschema (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"
  }
}

Blocktypen:

  • text: Einfacher Textabsatz

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

  • header: Überschrift (Level 1–6)

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

  • image: Bild mit optionaler Beschriftung

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

  • list: Geordnete oder ungeordnete Liste

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

  • code: Codeblock mit Sprache

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

  • video: Video-Einbettung

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

Fehlerantworten:

  • 400 Bad Request: Ungültiges Artikel-ID-Format
  • 401 Unauthorized: Ungültiger API-Key
  • 402 Payment Required: API-Quote überschritten
  • 404 Not Found: Artikel oder Workspace nicht gefunden
  • 500 Internal Server Error: Serverfehler

Beispielanfrage:

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

5. Artikel eines Agents abrufen

Endpunkt: GET /agents/{agentId}/articles

Kurzbeschreibung: Artikel eines bestimmten Agents abrufen

Beschreibung: Ruft alle von einem bestimmten Agent erstellten Artikel mit Filterung und Pagination ab. Gibt Artikel nach dem neuesten Datum zuerst zurück. Erfordert Authentifizierung über den x-api-key-Header sowie eine gültige API-Quote.

Authentifizierung: Erforderlich (x-api-key)

Tags: Agents

Pfadparameter:

ParameterTypBeschreibungBeispiel
agentIdstringDie MongoDB-ObjectId des Agents507f1f77bcf86cd799439011

Query-Parameter:

ParameterTypStandardBeschreibungBeispiel
limitnumber50Maximale Anzahl zurückzugebender Artikel30
skipnumber0Anzahl der zu überspringenden Datensätze für Pagination0
statusstringoptionalFilter nach Artikelstatus (draft, published, archived)published
sortstringcreatedAtFeld, nach dem sortiert wirdcreatedAt
orderenumdescSortierrichtung (asc oder desc)desc
slugstringoptionalFiltert Artikel nach URL-freundlichem Sluggetting-started-with-nextjs

Antwortschema (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
  }
}

Fehlerantworten:

  • 400 Bad Request: Ungültiges Agent-ID-Format
  • 401 Unauthorized: Ungültiger API-Key
  • 402 Payment Required: API-Quote überschritten
  • 404 Not Found: Agent oder Workspace nicht gefunden
  • 500 Internal Server Error: Serverfehler

Beispielanfrage:

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. Workspace-Daten abrufen

Endpunkt: GET /workspaces/{workspaceId}

Kurzbeschreibung: Workspace-Daten abrufen

Beschreibung: Ruft vollständige Workspace-Daten inklusive Workspace-Metadaten, aller Agents und deren veröffentlichten Artikel mit vollständigem Inhalt ab. Gibt verschachtelte Agents mit Artikeln zurück, um einfach auf die Inhaltsstruktur des Workspace zugreifen zu können. Erfordert API-Key-Authentifizierung, die zur abgefragten Workspace-ID passen muss.

Authentifizierung: Erforderlich (x-api-key) – Muss mit dem abgefragten Workspace übereinstimmen

Tags: Workspaces

Pfadparameter:

ParameterTypBeschreibungBeispiel
workspaceIdstringDie MongoDB-ObjectId des abzurufenden Workspace507f1f77bcf86cd799439010

Antwortschema (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"
        }
      ]
    }
  ]
}

Fehlerantworten:

  • 400 Bad Request: Ungültiges Workspace-ID-Format
  • 401 Unauthorized: Ungültiger API-Key oder Workspace-Mismatch
  • 402 Payment Required: API-Quote überschritten
  • 404 Not Found: Workspace nicht gefunden
  • 500 Internal Server Error: Serverfehler

Beispielanfrage:

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

Fehlerbehandlung

Alle Endpunkte geben standardisierte Fehlerantworten mit HTTP-Statuscodes zurück:

Fehlerantwort-Format

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

HTTP-Statuscodes

StatusBeschreibung
200Erfolg – Anfrage wurde erfolgreich abgeschlossen
400Bad Request – Ungültige Query-Parameter oder ungültiges Pfadformat
401Unauthorized – Ungültiger oder fehlender API-Key
402Payment Required – API-Quote für den Workspace-Plan überschritten
404Not Found – Ressource existiert nicht
500Internal Server Error – Serverseitiger Fehler aufgetreten

Quotensystem

Jeder Workspace hat eine API-Call-Quote basierend auf seinem Abonnementplan. Die Quote wird monatlich zurückgesetzt und bei jeder Anfrage erzwungen.

Plan-Limits

  • Free: 0 API-Aufrufe/Monat
  • Starter: 0 API-Aufrufe/Monat
  • Pro: 10.000 API-Aufrufe/Monat
  • Agency: ~ API-Aufrufe/Monat
  • Enterprise: Unbegrenzt

Quota Enforcement

Jede API-Anfrage zählt als 1 Aufruf zur monatlichen Quote. Wenn die Quote überschritten wird:

  • HTTP-Status: 402 Payment Required
  • Antwort: { error: "API access quota exceeded" }

Antwortformate

Erfolgsantwort

Alle erfolgreichen Antworten liefern den Statuscode 200 mit JSON-Daten:

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

Pagination-Format

Alle Listen-Endpunkte verwenden konsistente Pagination-Metadaten:

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

Fehlerantwort

Alle Fehlerantworten enthalten error- und details-Felder:

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

Endpoint-Übersicht

MethodEndpointBeschreibung
GET/agentsAgents mit Pagination und Filtern auflisten
GET/agents/{agentId}Einzelnen Agent per ID abrufen
GET/articlesArtikel mit Pagination und erweiterten Filtern auflisten
GET/articles/{articleId}Einzelnen Artikel per ID mit vollständigem Inhalt abrufen
GET/agents/{agentId}/articlesArtikel eines bestimmten Agents abrufen
GET/workspaces/{workspaceId}Workspace mit allen Agents und Artikeln abrufen
OPTIONS/*CORS-Preflight-Unterstützung

Best Practices

Pagination

  • Verwende immer Pagination bei Listen-Endpunkten, um Timeouts zu vermeiden
  • Starte mit skip: 0 und limit: 25-50
  • Verwende hasNextPage, um festzustellen, ob weitere Ergebnisse vorhanden sind
  • Implementiere exponentielles Backoff bei fehlgeschlagenen Anfragen

Filtering

  • Verwende spezifische Filter, um die Antwortgröße zu reduzieren
  • Filtere nach status und language, um Ergebnisse einzugrenzen
  • Verwende search für Volltextsuche, statt alle Datensätze abzurufen

Error Handling

  • Prüfe immer auf 401- (Authentifizierung) und 402-Fehler (Quote)
  • Implementiere Retry-Logik mit exponentiellem Backoff
  • Protokolliere Fehlerdetails für das Debugging
  • Behandle 4xx-Fehler als Client-Probleme, 5xx als Server-Probleme

Performance

  • Cache Ergebnisse 5–10 Minuten, um API-Aufrufe zu reduzieren
  • Verwende limit=50 für optimale Performance
  • Kombiniere Filter, um die Ergebnismenge zu minimieren
  • Berücksichtige die Batch-Größe bei Pagination anhand der Quotenlimits

Dokumentversion: 2.0 Zuletzt aktualisiert: Januar 2026 API-Version: v1 Status: Produktionsbereit für SDK-Generierung

Inkpilots V1 API Documentation

Purpose: Complete API reference for the V1 public API with full endpoint descriptions, query parameters, authentication, response formats, and quota system for Node.js SDK generation.

Table of Contents

  1. Authentication
  2. Base URL & CORS
  3. API Endpoints
  4. Error Handling
  5. Quota System
  6. Response Formats
  7. Endpoint Summary

Authentication

API Key Authentication

All V1 API endpoints require authentication via API key. The API key is passed in the request header.

Header Format:

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

Example:

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

Verification Flow

  1. Client sends request with x-api-key header
  2. Server calls verifyApiKey(apiKeyHeader) function
  3. If valid, returns:
    • isValid: boolean
    • workspaceId: string (MongoDB ObjectId as string)
  4. If invalid, returns { isValid: false }

Error Responses

  • 401 Unauthorized: Invalid or missing API key, or insufficient permissions
  • 402 Payment Required: API access quota exceeded for the workspace's plan

Base URL & CORS

Base URL

https://inkpilots.com/api/v1

CORS Headers

All responses include the following CORS headers:

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

Note: CORS allows all origins because the API does not use cookies (stateless authentication).

Preflight Requests

All endpoints support OPTIONS requests for CORS preflight:

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

Response: 204 No Content with CORS headers.

API Endpoints

1. List Agents

Endpoint: GET /agents

Summary: List agents

Description: Fetch a paginated list of agents with advanced filtering by status, execution mode, LLM model, and full-text search across name and prompt. Requires authentication via x-api-key header and valid API quota.

Authentication: Required (x-api-key)

Tags: Agents

Query Parameters:

ParameterTypeDefaultDescriptionExample
skipnumber0Number of agents to skip for pagination (offset)0
limitnumber10Maximum number of agents to return per page (capped at 100)20
sortBystringcreatedAtField to sort agents by (e.g., name, createdAt, model, isActive)createdAt
sortOrderenumdescSort direction (ascending or descending)desc
statusenumoptionalFilter agents by status (active or inactive)active
executionModeenumoptionalFilter agents by execution mode (scheduled or batched)scheduled
modelstringoptionalFilter agents by LLM model namellama-2-70b-chat
searchstringoptionalFull-text search in agent name and prompt (case-insensitive)blog writer

Response Schema (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
  }
}

Error Responses:

  • 400 Bad Request: Invalid query parameters
  • 401 Unauthorized: Invalid API key
  • 402 Payment Required: API quota exceeded
  • 404 Not Found: Workspace not found
  • 500 Internal Server Error: Server error

Example Request:

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. Get Agent by ID

Endpoint: GET /agents/{agentId}

Summary: Get agent by ID

Description: Fetch a single agent's complete configuration and metadata. Requires authentication via x-api-key header and valid API quota.

Authentication: Required (x-api-key)

Tags: Agents

Path Parameters:

ParameterTypeDescriptionExample
agentIdstringThe MongoDB ObjectId of the agent to retrieve507f1f77bcf86cd799439011

Response Schema (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"
  }
}

Error Responses:

  • 400 Bad Request: Invalid agent ID format
  • 401 Unauthorized: Invalid API key
  • 402 Payment Required: API quota exceeded
  • 404 Not Found: Agent or workspace not found
  • 500 Internal Server Error: Server error

Example Request:

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

3. List Articles

Endpoint: GET /articles

Summary: List articles

Description: Fetch a paginated list of articles with advanced filtering by agent, status, language, tags, and full-text search across title, description, and keywords. Requires authentication via x-api-key header and valid API quota.

Authentication: Required (x-api-key)

Tags: Articles

Query Parameters:

ParameterTypeDefaultDescriptionExample
skipnumber0Number of articles to skip for pagination (offset)0
limitnumber10Maximum number of articles to return per page (capped at 100)20
sortBystringcreatedAtField to sort articles by (e.g., title, createdAt, status, updatedAt)createdAt
sortOrderenumdescSort direction (ascending or descending)desc
agentIdstringoptionalFilter articles by source agent ID (MongoDB ObjectId)507f1f77bcf86cd799439011
statusenumoptionalFilter articles by publication status (draft, published, archived)published
slugstringoptionalFilter articles by given slug.generic-article-slug-as-example
languagestringoptionalFilter articles by language code (e.g., en, tr, de)en
modelstringoptionalFilter articles by LLM model used for generationllama-2-70b-chat
tagsstringoptionalFilter by tags (comma-separated, matches any tag)featured,trending,tech
searchstringoptionalFull-text search in title, description, keywords, and tags (case-insensitive)artificial intelligence

Response Schema (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
  }
}

Error Responses:

  • 400 Bad Request: Invalid query parameters
  • 401 Unauthorized: Invalid API key
  • 402 Payment Required: API quota exceeded
  • 404 Not Found: Workspace not found
  • 500 Internal Server Error: Server error

Example Request:

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. Get Article by ID

Endpoint: GET /articles/{articleId}

Summary: Get article by ID

Description: Fetch a single article by its ID with complete content and structured blocks. Requires authentication via x-api-key header and valid API quota.

Authentication: Required (x-api-key)

Tags: Articles

Path Parameters:

ParameterTypeDescriptionExample
articleIdstringThe MongoDB ObjectId of the article to retrieve607f1f77bcf86cd799439012

Response Schema (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"
  }
}

Block Types:

  • text: Plain text paragraph

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

  • header: Heading (levels 1-6)

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

  • image: Image with optional caption

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

  • list: Ordered or unordered list

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

  • code: Code block with language

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

  • video: Video embed

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

Error Responses:

  • 400 Bad Request: Invalid article ID format
  • 401 Unauthorized: Invalid API key
  • 402 Payment Required: API quota exceeded
  • 404 Not Found: Article or workspace not found
  • 500 Internal Server Error: Server error

Example Request:

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

5. Get Agent Articles

Endpoint: GET /agents/{agentId}/articles

Summary: Get articles from specific agent

Description: Fetch all articles created by a specific agent with filtering and pagination. Returns articles sorted by newest first. Requires authentication via x-api-key header and valid API quota.

Authentication: Required (x-api-key)

Tags: Agents

Path Parameters:

ParameterTypeDescriptionExample
agentIdstringThe MongoDB ObjectId of the agent507f1f77bcf86cd799439011

Query Parameters:

ParameterTypeDefaultDescriptionExample
limitnumber50Maximum number of articles to return30
skipnumber0Number of records to skip for pagination0
statusstringoptionalFilter by article status (draft, published, archived)published
sortstringcreatedAtField to sort bycreatedAt
orderenumdescSort direction (asc or desc)desc
slugstringoptionalFilter articles by URL-friendly sluggetting-started-with-nextjs

Response Schema (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
  }
}

Error Responses:

  • 400 Bad Request: Invalid agent ID format
  • 401 Unauthorized: Invalid API key
  • 402 Payment Required: API quota exceeded
  • 404 Not Found: Agent or workspace not found
  • 500 Internal Server Error: Server error

Example Request:

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. Get Workspace Data

Endpoint: GET /workspaces/{workspaceId}

Summary: Get workspace data

Description: Fetch complete workspace data including workspace metadata, all agents, and their published articles with full content. Returns nested agents with articles for easy access to workspace content structure. Requires API key authentication matching the workspace ID.

Authentication: Required (x-api-key) - Must match the workspace being accessed

Tags: Workspaces

Path Parameters:

ParameterTypeDescriptionExample
workspaceIdstringThe MongoDB ObjectId of the workspace to fetch507f1f77bcf86cd799439010

Response Schema (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"
        }
      ]
    }
  ]
}

Error Responses:

  • 400 Bad Request: Invalid workspace ID format
  • 401 Unauthorized: Invalid API key or workspace mismatch
  • 402 Payment Required: API quota exceeded
  • 404 Not Found: Workspace not found
  • 500 Internal Server Error: Server error

Example Request:

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

Error Handling

All endpoints return standardized error responses with HTTP status codes:

Error Response Format

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

HTTP Status Codes

StatusDescription
200Success - Request completed successfully
400Bad Request - Invalid query parameters or path format
401Unauthorized - Invalid or missing API key
402Payment Required - API quota exceeded for workspace plan
404Not Found - Resource does not exist
500Internal Server Error - Server-side error occurred

Quota System

Each workspace has an API call quota based on its subscription plan. The quota resets monthly and is enforced on every request.

Plan Limits

  • Free: 0 API calls/month
  • Starter: 0 API calls/month
  • Pro: 10,000 API calls/month
  • Agency: ~ API calls/month
  • Enterprise: Unlimited

Quota Enforcement

Each API request counts as 1 call toward the monthly quota. When quota is exceeded:

  • HTTP Status: 402 Payment Required
  • Response: { error: "API access quota exceeded" }

Response Formats

Success Response

All successful responses return a 200 status code with JSON data:

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

Pagination Format

All list endpoints use consistent pagination metadata:

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

Error Response

All error responses include error and details fields:

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

Endpoint Summary

MethodEndpointDescription
GET/agentsList agents with pagination and filters
GET/agents/{agentId}Get single agent by ID
GET/articlesList articles with pagination and advanced filters
GET/articles/{articleId}Get single article by ID with complete content
GET/agents/{agentId}/articlesGet articles from specific agent
GET/workspaces/{workspaceId}Get workspace with all agents and articles
OPTIONS/*CORS preflight support

Best Practices

Pagination

  • Always use pagination for list endpoints to avoid timeouts
  • Start with skip: 0 and limit: 25-50
  • Use hasNextPage to determine if more results exist
  • Implement exponential backoff for failed requests

Filtering

  • Use specific filters to reduce response size
  • Filter by status and language to narrow results
  • Use search for full-text lookup instead of fetching all records

Error Handling

  • Always check for 401 (authentication) and 402 (quota) errors
  • Implement retry logic with exponential backoff
  • Log error details for debugging
  • Handle 4xx errors as client issues, 5xx as server issues

Performance

  • Cache results for 5-10 minutes to reduce API calls
  • Use limit=50 for optimal performance
  • Combine filters to minimize result set size
  • Consider pagination batch size based on quota limits

Document Version: 2.0 Last Updated: January 2026 API Version: v1 Status: Production Ready for SDK Generation