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.

Authentication
Base URL & CORS
API Endpoints
Error Handling
Quota System
Response Formats
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

Client sends request with x-api-key header
Server calls verifyApiKey(apiKeyHeader) function
If valid, returns:
- isValid: boolean
- workspaceId: string (MongoDB ObjectId as string)
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:

Parameter	Type	Default	Description	Example
skip	number	0	Number of agents to skip for pagination (offset)	0
limit	number	10	Maximum number of agents to return per page (capped at 100)	20
sortBy	string	createdAt	Field to sort agents by (e.g., name, createdAt, model, isActive)	createdAt
sortOrder	enum	desc	Sort direction (ascending or descending)	desc
status	enum	optional	Filter agents by status (active or inactive)	active
executionMode	enum	optional	Filter agents by execution mode (scheduled or batched)	scheduled
model	string	optional	Filter agents by LLM model name	llama-2-70b-chat
search	string	optional	Full-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:

Parameter	Type	Description	Example
agentId	string	The MongoDB ObjectId of the agent to retrieve	507f1f77bcf86cd799439011

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:

Parameter	Type	Default	Description	Example
skip	number	0	Number of articles to skip for pagination (offset)	0
limit	number	10	Maximum number of articles to return per page (capped at 100)	20
sortBy	string	createdAt	Field to sort articles by (e.g., title, createdAt, status, updatedAt)	createdAt
sortOrder	enum	desc	Sort direction (ascending or descending)	desc
agentId	string	optional	Filter articles by source agent ID (MongoDB ObjectId)	507f1f77bcf86cd799439011
status	enum	optional	Filter articles by publication status (draft, published, archived)	published
slug	string	optional	Filter articles by given slug.	generic-article-slug-as-example
language	string	optional	Filter articles by language code (e.g., en, tr, de)	en
model	string	optional	Filter articles by LLM model used for generation	llama-2-70b-chat
tags	string	optional	Filter by tags (comma-separated, matches any tag)	featured,trending,tech
search	string	optional	Full-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:

Parameter	Type	Description	Example
articleId	string	The MongoDB ObjectId of the article to retrieve	607f1f77bcf86cd799439012

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:

Parameter	Type	Description	Example
agentId	string	The MongoDB ObjectId of the agent	507f1f77bcf86cd799439011

Query Parameters:

Parameter	Type	Default	Description	Example
limit	number	50	Maximum number of articles to return	30
skip	number	0	Number of records to skip for pagination	0
status	string	optional	Filter by article status (draft, published, archived)	published
sort	string	createdAt	Field to sort by	createdAt
order	enum	desc	Sort direction (asc or desc)	desc
slug	string	optional	Filter articles by URL-friendly slug	getting-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:

Parameter	Type	Description	Example
workspaceId	string	The MongoDB ObjectId of the workspace to fetch	507f1f77bcf86cd799439010

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

Status	Description
200	Success - Request completed successfully
400	Bad Request - Invalid query parameters or path format
401	Unauthorized - Invalid or missing API key
402	Payment Required - API quota exceeded for workspace plan
404	Not Found - Resource does not exist
500	Internal 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

Method	Endpoint	Description
GET	/agents	List agents with pagination and filters
GET	/agents/{agentId}	Get single agent by ID
GET	/articles	List articles with pagination and advanced filters
GET	/articles/{articleId}	Get single article by ID with complete content
GET	/agents/{agentId}/articles	Get 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

Inkpilots V1 API Documentation

Table of Contents

Authentication

API Key Authentication

Verification Flow

Error Responses

Base URL & CORS

Base URL

CORS Headers

Preflight Requests

API Endpoints

1. List Agents

2. Get Agent by ID

3. List Articles

4. Get Article by ID

5. Get Agent Articles

6. Get Workspace Data

Error Handling

Error Response Format

HTTP Status Codes

Quota System

Plan Limits

Quota Enforcement

Response Formats

Success Response

Pagination Format

Error Response

Endpoint Summary

Best Practices

Pagination

Filtering

Error Handling

Performance