Inkpilots V1 API ドキュメント

目的: V1 公開 API の完全リファレンス。Node.js SDK 生成向けに、全エンドポイントの説明、クエリパラメータ、認証、レスポンス形式、クォータシステムを網羅します。

認証

API キー認証

すべての V1 API エンドポイントは API キーによる認証が必要です。API キーはリクエストヘッダーで渡します。

ヘッダー形式:

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

例:

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

検証フロー

クライアントが x-api-key ヘッダー付きでリクエストを送信
サーバーが verifyApiKey(apiKeyHeader) 関数を呼び出し
有効な場合、以下を返却:
- isValid: boolean
- workspaceId: string（MongoDB ObjectId の文字列表現）
無効な場合、{ isValid: false } を返却

エラーレスポンス

401 Unauthorized: API キーが無効・欠落、または権限不足
402 Payment Required: ワークスペースプランの API アクセスクォータを超過

ベース URL と CORS

ベース URL

https://inkpilots.com/api/v1

CORS ヘッダー

すべてのレスポンスに以下の CORS ヘッダーが含まれます:

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

注記: API は Cookie を使用しない（ステートレス認証）ため、すべてのオリジンを許可しています。

プリフライトリクエスト

すべてのエンドポイントは CORS プリフライト用の OPTIONS リクエストをサポートします:

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

レスポンス: CORS ヘッダー付き 204 No Content。

API エンドポイント

1. エージェント一覧

エンドポイント: GET /agents

概要: エージェント一覧取得

説明: ステータス、実行モード、LLM モデル、名前・プロンプト全文検索による高度なフィルタに対応したページネーション付きエージェント一覧を取得します。x-api-key ヘッダーによる認証と有効な API クォータが必要です。

認証: 必須（x-api-key）

タグ: Agents

クエリパラメータ:

パラメータ	型	デフォルト	説明	例
skip	number	0	ページネーション用にスキップする件数（オフセット）	0
limit	number	10	返却する最大件数（上限 100）	20
sortBy	string	createdAt	ソート対象フィールド（例: name, createdAt, model, isActive）	createdAt
sortOrder	enum	desc	ソート順（昇順/降順）	desc
status	enum	optional	ステータスで絞り込み（active/inactive）	active
executionMode	enum	optional	実行モードで絞り込み（scheduled/batched）	scheduled
model	string	optional	LLM モデル名で絞り込み	llama-2-70b-chat
search	string	optional	名前・プロンプトの全文検索（大文字小文字を区別しない）	blog writer

レスポンススキーマ（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
  }
}

エラーレスポンス:

400 Bad Request: クエリパラメータが不正
401 Unauthorized: API キーが無効
402 Payment Required: API クォータ超過
404 Not Found: ワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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. エージェント ID 指定取得

エンドポイント: GET /agents/{agentId}

概要: ID でエージェント取得

説明: 単一エージェントの完全な設定とメタデータを取得します。x-api-key ヘッダーによる認証と有効な API クォータが必要です。

認証: 必須（x-api-key）

タグ: Agents

パスパラメータ:

パラメータ	型	説明	例
agentId	string	取得対象エージェントの MongoDB ObjectId	507f1f77bcf86cd799439011

レスポンススキーマ（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"
  }
}

エラーレスポンス:

400 Bad Request: agent ID 形式が不正
401 Unauthorized: API キーが無効
402 Payment Required: API クォータ超過
404 Not Found: エージェントまたはワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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

3. 記事一覧

エンドポイント: GET /articles

概要: 記事一覧取得

説明: エージェント、ステータス、言語、タグ、タイトル・説明・キーワード全文検索による高度なフィルタに対応したページネーション付き記事一覧を取得します。x-api-key ヘッダーによる認証と有効な API クォータが必要です。

認証: 必須（x-api-key）

タグ: Articles

クエリパラメータ:

パラメータ	型	デフォルト	説明	例
skip	number	0	ページネーション用にスキップする件数（オフセット）	0
limit	number	10	返却する最大件数（上限 100）	20
sortBy	string	createdAt	ソート対象フィールド（例: title, createdAt, status, updatedAt）	createdAt
sortOrder	enum	desc	ソート順（昇順/降順）	desc
agentId	string	optional	生成元エージェント ID（MongoDB ObjectId）で絞り込み	507f1f77bcf86cd799439011
status	enum	optional	公開状態で絞り込み（draft, published, archived）	published
slug	string	optional	指定 slug で絞り込み	generic-article-slug-as-example
language	string	optional	言語コードで絞り込み（例: en, tr, de）	en
model	string	optional	生成に使用した LLM モデルで絞り込み	llama-2-70b-chat
tags	string	optional	タグで絞り込み（カンマ区切り、いずれか一致）	featured,trending,tech
search	string	optional	タイトル・説明・キーワード・タグの全文検索（大文字小文字を区別しない）	artificial intelligence

レスポンススキーマ（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
  }
}

エラーレスポンス:

400 Bad Request: クエリパラメータが不正
401 Unauthorized: API キーが無効
402 Payment Required: API クォータ超過
404 Not Found: ワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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. 記事 ID 指定取得

エンドポイント: GET /articles/{articleId}

概要: ID で記事取得

説明: 単一記事を ID で取得し、完全な本文と構造化ブロックを返します。x-api-key ヘッダーによる認証と有効な API クォータが必要です。

認証: 必須（x-api-key）

タグ: Articles

パスパラメータ:

パラメータ	型	説明	例
articleId	string	取得対象記事の MongoDB ObjectId	607f1f77bcf86cd799439012

レスポンススキーマ（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"
  }
}

ブロックタイプ:

text: 通常の段落テキスト

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

header: 見出し（レベル 1〜6）

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

image: 画像（キャプション任意）

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

list: 順序付き/順序なしリスト

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

code: 言語指定付きコードブロック

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

video: 動画埋め込み

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

エラーレスポンス:

400 Bad Request: article ID 形式が不正
401 Unauthorized: API キーが無効
402 Payment Required: API クォータ超過
404 Not Found: 記事またはワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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

5. エージェントの記事取得

エンドポイント: GET /agents/{agentId}/articles

概要: 特定エージェントの記事取得

説明: 特定エージェントが作成した記事を、フィルタ・ページネーション付きで取得します。新しい順で返却されます。x-api-key ヘッダーによる認証と有効な API クォータが必要です。

認証: 必須（x-api-key）

タグ: Agents

パスパラメータ:

パラメータ	型	説明	例
agentId	string	エージェントの MongoDB ObjectId	507f1f77bcf86cd799439011

クエリパラメータ:

パラメータ	型	デフォルト	説明	例
limit	number	50	返却する最大記事数	30
skip	number	0	ページネーション用のスキップ件数	0
status	string	optional	記事ステータスで絞り込み（draft, published, archived）	published
sort	string	createdAt	ソート対象フィールド	createdAt
order	enum	desc	ソート順（asc/desc）	desc
slug	string	optional	URL フレンドリーな slug で絞り込み	getting-started-with-nextjs

レスポンススキーマ（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
  }
}

エラーレスポンス:

400 Bad Request: agent ID 形式が不正
401 Unauthorized: API キーが無効
402 Payment Required: API クォータ超過
404 Not Found: エージェントまたはワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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 /workspaces/{workspaceId}

概要: ワークスペースデータ取得

説明: ワークスペースのメタデータ、全エージェント、およびそれらの公開済み記事（完全コンテンツ含む）を取得します。ネストされたエージェント配下に記事を含めて返却し、ワークスペースのコンテンツ構造に容易にアクセスできます。アクセス先ワークスペース ID に一致する API キー認証が必要です。

認証: 必須（x-api-key）- アクセス対象ワークスペースとの一致が必要

タグ: Workspaces

パスパラメータ:

パラメータ	型	説明	例
workspaceId	string	取得対象ワークスペースの MongoDB ObjectId	507f1f77bcf86cd799439010

レスポンススキーマ（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"
        }
      ]
    }
  ]
}

エラーレスポンス:

400 Bad Request: workspace ID 形式が不正
401 Unauthorized: API キー無効またはワークスペース不一致
402 Payment Required: API クォータ超過
404 Not Found: ワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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

エラーハンドリング

すべてのエンドポイントは HTTP ステータスコードとともに標準化されたエラーレスポンスを返します。

エラーレスポンス形式

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

HTTP ステータスコード

ステータス	説明
200	Success - リクエスト成功
400	Bad Request - クエリパラメータまたはパス形式が不正
401	Unauthorized - API キーが無効または欠落
402	Payment Required - ワークスペースプランの API クォータ超過
404	Not Found - リソースが存在しない
500	Internal Server Error - サーバー側エラー

クォータシステム

各ワークスペースにはサブスクリプションプランに基づく API 呼び出しクォータがあります。クォータは毎月リセットされ、すべてのリクエストで適用されます。

プラン制限

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

クォータ適用

各 API リクエストは月間クォータに対して 1 コールとしてカウントされます。クォータ超過時:

HTTP ステータス: 402 Payment Required
レスポンス: { error: "API access quota exceeded" }

レスポンス形式

成功レスポンス

成功時はすべて 200 ステータスコードと JSON データを返します:

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

ページネーション形式

一覧系エンドポイントは統一されたページネーションメタデータを返します:

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

エラーレスポンス

すべてのエラーレスポンスは error と details を含みます:

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

エンドポイント一覧

Method	Endpoint	Description
GET	/agents	ページネーション・フィルタ付きでエージェント一覧取得
GET	/agents/{agentId}	単一エージェントを ID 指定で取得
GET	/articles	ページネーション・高度フィルタ付きで記事一覧取得
GET	/articles/{articleId}	単一記事を ID 指定で完全コンテンツ付き取得
GET	/agents/{agentId}/articles	特定エージェントの記事取得
GET	/workspaces/{workspaceId}	ワークスペースと全エージェント・記事を取得
OPTIONS	/*	CORS プリフライトサポート

ベストプラクティス

ページネーション

タイムアウト回避のため一覧系では必ずページネーションを使用
skip: 0 と limit: 25-50 から開始
hasNextPage を使って次ページ有無を判定
失敗時は指数バックオフを実装

フィルタリング

レスポンスサイズ削減のため具体的なフィルタを使用
status と language で対象を絞り込み
全件取得より search による全文検索を優先

エラーハンドリング

401（認証）と 402（クォータ）を必ず判定
指数バックオフ付きリトライを実装
デバッグ用にエラー詳細をログ化
4xx はクライアント起因、5xx はサーバー起因として扱う

パフォーマンス

API コール削減のため結果を 5〜10 分キャッシュ
最適なパフォーマンスのため limit=50 を推奨
フィルタを組み合わせて結果セットを最小化
クォータ制限を考慮してページサイズを設計

ドキュメントバージョン: 2.0 最終更新: January 2026 API バージョン: v1 ステータス: SDK 生成向け本番対応

Inkpilots V1 API ドキュメント

認証

API キー認証

すべての V1 API エンドポイントは API キーによる認証が必要です。API キーはリクエストヘッダーで渡します。

ヘッダー形式:

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

例:

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

検証フロー

クライアントが x-api-key ヘッダー付きでリクエストを送信
サーバーが verifyApiKey(apiKeyHeader) 関数を呼び出し
有効な場合、以下を返却:
- isValid: boolean
- workspaceId: string（MongoDB ObjectId の文字列表現）
無効な場合、{ isValid: false } を返却

エラーレスポンス

401 Unauthorized: API キーが無効・欠落、または権限不足
402 Payment Required: ワークスペースプランの API アクセスクォータを超過

ベース URL と CORS

ベース URL

https://inkpilots.com/api/v1

CORS ヘッダー

すべてのレスポンスに以下の CORS ヘッダーが含まれます:

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

注記: API は Cookie を使用しない（ステートレス認証）ため、すべてのオリジンを許可しています。

プリフライトリクエスト

すべてのエンドポイントは CORS プリフライト用の OPTIONS リクエストをサポートします:

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

レスポンス: CORS ヘッダー付き 204 No Content。

API エンドポイント

1. エージェント一覧

エンドポイント: GET /agents

概要: エージェント一覧取得

認証: 必須（x-api-key）

タグ: Agents

クエリパラメータ:

パラメータ	型	デフォルト	説明	例
skip	number	0	ページネーション用にスキップする件数（オフセット）	0
limit	number	10	返却する最大件数（上限 100）	20
sortBy	string	createdAt	ソート対象フィールド（例: name, createdAt, model, isActive）	createdAt
sortOrder	enum	desc	ソート順（昇順/降順）	desc
status	enum	optional	ステータスで絞り込み（active/inactive）	active
executionMode	enum	optional	実行モードで絞り込み（scheduled/batched）	scheduled
model	string	optional	LLM モデル名で絞り込み	llama-2-70b-chat
search	string	optional	名前・プロンプトの全文検索（大文字小文字を区別しない）	blog writer

レスポンススキーマ（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
  }
}

エラーレスポンス:

400 Bad Request: クエリパラメータが不正
401 Unauthorized: API キーが無効
402 Payment Required: API クォータ超過
404 Not Found: ワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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. エージェント ID 指定取得

エンドポイント: GET /agents/{agentId}

概要: ID でエージェント取得

説明: 単一エージェントの完全な設定とメタデータを取得します。x-api-key ヘッダーによる認証と有効な API クォータが必要です。

認証: 必須（x-api-key）

タグ: Agents

パスパラメータ:

パラメータ	型	説明	例
agentId	string	取得対象エージェントの MongoDB ObjectId	507f1f77bcf86cd799439011

レスポンススキーマ（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"
  }
}

エラーレスポンス:

400 Bad Request: agent ID 形式が不正
401 Unauthorized: API キーが無効
402 Payment Required: API クォータ超過
404 Not Found: エージェントまたはワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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

3. 記事一覧

エンドポイント: GET /articles

概要: 記事一覧取得

認証: 必須（x-api-key）

タグ: Articles

クエリパラメータ:

パラメータ	型	デフォルト	説明	例
skip	number	0	ページネーション用にスキップする件数（オフセット）	0
limit	number	10	返却する最大件数（上限 100）	20
sortBy	string	createdAt	ソート対象フィールド（例: title, createdAt, status, updatedAt）	createdAt
sortOrder	enum	desc	ソート順（昇順/降順）	desc
agentId	string	optional	生成元エージェント ID（MongoDB ObjectId）で絞り込み	507f1f77bcf86cd799439011
status	enum	optional	公開状態で絞り込み（draft, published, archived）	published
slug	string	optional	指定 slug で絞り込み	generic-article-slug-as-example
language	string	optional	言語コードで絞り込み（例: en, tr, de）	en
model	string	optional	生成に使用した LLM モデルで絞り込み	llama-2-70b-chat
tags	string	optional	タグで絞り込み（カンマ区切り、いずれか一致）	featured,trending,tech
search	string	optional	タイトル・説明・キーワード・タグの全文検索（大文字小文字を区別しない）	artificial intelligence

レスポンススキーマ（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
  }
}

エラーレスポンス:

400 Bad Request: クエリパラメータが不正
401 Unauthorized: API キーが無効
402 Payment Required: API クォータ超過
404 Not Found: ワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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. 記事 ID 指定取得

エンドポイント: GET /articles/{articleId}

概要: ID で記事取得

説明: 単一記事を ID で取得し、完全な本文と構造化ブロックを返します。x-api-key ヘッダーによる認証と有効な API クォータが必要です。

認証: 必須（x-api-key）

タグ: Articles

パスパラメータ:

パラメータ	型	説明	例
articleId	string	取得対象記事の MongoDB ObjectId	607f1f77bcf86cd799439012

レスポンススキーマ（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"
  }
}

ブロックタイプ:

text: 通常の段落テキスト

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

header: 見出し（レベル 1〜6）

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

image: 画像（キャプション任意）

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

list: 順序付き/順序なしリスト

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

code: 言語指定付きコードブロック

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

video: 動画埋め込み

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

エラーレスポンス:

400 Bad Request: article ID 形式が不正
401 Unauthorized: API キーが無効
402 Payment Required: API クォータ超過
404 Not Found: 記事またはワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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

5. エージェントの記事取得

エンドポイント: GET /agents/{agentId}/articles

概要: 特定エージェントの記事取得

認証: 必須（x-api-key）

タグ: Agents

パスパラメータ:

パラメータ	型	説明	例
agentId	string	エージェントの MongoDB ObjectId	507f1f77bcf86cd799439011

クエリパラメータ:

パラメータ	型	デフォルト	説明	例
limit	number	50	返却する最大記事数	30
skip	number	0	ページネーション用のスキップ件数	0
status	string	optional	記事ステータスで絞り込み（draft, published, archived）	published
sort	string	createdAt	ソート対象フィールド	createdAt
order	enum	desc	ソート順（asc/desc）	desc
slug	string	optional	URL フレンドリーな slug で絞り込み	getting-started-with-nextjs

レスポンススキーマ（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
  }
}

エラーレスポンス:

400 Bad Request: agent ID 形式が不正
401 Unauthorized: API キーが無効
402 Payment Required: API クォータ超過
404 Not Found: エージェントまたはワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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 /workspaces/{workspaceId}

概要: ワークスペースデータ取得

認証: 必須（x-api-key）- アクセス対象ワークスペースとの一致が必要

タグ: Workspaces

パスパラメータ:

パラメータ	型	説明	例
workspaceId	string	取得対象ワークスペースの MongoDB ObjectId	507f1f77bcf86cd799439010

レスポンススキーマ（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"
        }
      ]
    }
  ]
}

エラーレスポンス:

400 Bad Request: workspace ID 形式が不正
401 Unauthorized: API キー無効またはワークスペース不一致
402 Payment Required: API クォータ超過
404 Not Found: ワークスペースが見つからない
500 Internal Server Error: サーバーエラー

リクエスト例:

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

エラーハンドリング

すべてのエンドポイントは HTTP ステータスコードとともに標準化されたエラーレスポンスを返します。

エラーレスポンス形式

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

HTTP ステータスコード

ステータス	説明
200	Success - リクエスト成功
400	Bad Request - クエリパラメータまたはパス形式が不正
401	Unauthorized - API キーが無効または欠落
402	Payment Required - ワークスペースプランの API クォータ超過
404	Not Found - リソースが存在しない
500	Internal Server Error - サーバー側エラー

クォータシステム

プラン制限

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

クォータ適用

各 API リクエストは月間クォータに対して 1 コールとしてカウントされます。クォータ超過時:

HTTP ステータス: 402 Payment Required
レスポンス: { error: "API access quota exceeded" }

レスポンス形式

成功レスポンス

成功時はすべて 200 ステータスコードと JSON データを返します:

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

ページネーション形式

一覧系エンドポイントは統一されたページネーションメタデータを返します:

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

エラーレスポンス

すべてのエラーレスポンスは error と details を含みます:

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

エンドポイント一覧

Method	Endpoint	Description
GET	/agents	ページネーション・フィルタ付きでエージェント一覧取得
GET	/agents/{agentId}	単一エージェントを ID 指定で取得
GET	/articles	ページネーション・高度フィルタ付きで記事一覧取得
GET	/articles/{articleId}	単一記事を ID 指定で完全コンテンツ付き取得
GET	/agents/{agentId}/articles	特定エージェントの記事取得
GET	/workspaces/{workspaceId}	ワークスペースと全エージェント・記事を取得
OPTIONS	/*	CORS プリフライトサポート

ベストプラクティス

ページネーション

タイムアウト回避のため一覧系では必ずページネーションを使用
skip: 0 と limit: 25-50 から開始
hasNextPage を使って次ページ有無を判定
失敗時は指数バックオフを実装

フィルタリング

レスポンスサイズ削減のため具体的なフィルタを使用
status と language で対象を絞り込み
全件取得より search による全文検索を優先

エラーハンドリング

401（認証）と 402（クォータ）を必ず判定
指数バックオフ付きリトライを実装
デバッグ用にエラー詳細をログ化
4xx はクライアント起因、5xx はサーバー起因として扱う

パフォーマンス

API コール削減のため結果を 5〜10 分キャッシュ
最適なパフォーマンスのため limit=50 を推奨
フィルタを組み合わせて結果セットを最小化
クォータ制限を考慮してページサイズを設計

ドキュメントバージョン: 2.0 最終更新: January 2026 API バージョン: v1 ステータス: SDK 生成向け本番対応

Inkpilots V1 API ドキュメント

目次

認証

API キー認証

検証フロー

エラーレスポンス

ベース URL と CORS

ベース URL

CORS ヘッダー

プリフライトリクエスト

API エンドポイント

1. エージェント一覧

2. エージェント ID 指定取得

3. 記事一覧

4. 記事 ID 指定取得

5. エージェントの記事取得

6. ワークスペースデータ取得

エラーハンドリング

エラーレスポンス形式

HTTP ステータスコード

クォータシステム

プラン制限

クォータ適用

レスポンス形式

成功レスポンス

ページネーション形式

エラーレスポンス

エンドポイント一覧

ベストプラクティス

ページネーション

フィルタリング

エラーハンドリング

パフォーマンス

Inkpilots V1 API ドキュメント

目次

認証

API キー認証

検証フロー

エラーレスポンス

ベース URL と CORS

ベース URL

CORS ヘッダー

プリフライトリクエスト

API エンドポイント

1. エージェント一覧

2. エージェント ID 指定取得

3. 記事一覧

4. 記事 ID 指定取得

5. エージェントの記事取得

6. ワークスペースデータ取得

エラーハンドリング

エラーレスポンス形式

HTTP ステータスコード

クォータシステム

プラン制限

クォータ適用

レスポンス形式

成功レスポンス

ページネーション形式

エラーレスポンス

エンドポイント一覧

ベストプラクティス

ページネーション

フィルタリング

エラーハンドリング

パフォーマンス