# クイックスタート

> キーの作成から最初の呼び出しまで。キーを作成し、ツール、エージェント、MCP クライアントを呼び出します。

Source: https://piqline.com/ja/docs/api

Piqline API を使うと、スクリプトやエージェントからワークスペースにアクセスできます。ダッシュボードのアシスタントと同じツールと同じエージェントを、HTTP または MCP（Model Context Protocol）で利用できます。各呼び出しは 1 つのワークスペースを対象とし、キーを作成したメンバーの権限で実行されます。

## 必要なもの

- オーナーまたは管理者として参加している Piqline ワークスペース。メンバーはキーのページを閲覧のみできます。
- HTTP リクエストを送れるツール（例では `curl`）、または MCP クライアント。

## 1. キーを作成する

1. [設定 → API と MCP](/settings/api) を開きます。
2. キーに名前を付け、スコープにチェックを入れ（最初は `read`）、有効期限を選びます。
3. **キーを作成** をクリックし、キーをコピーします。キーが表示されるのは 1 回だけです。

> **警告.** キーはあなたの権限でワークスペースに対して動作します。シークレット管理ツールか環境変数に保存し、コードやリポジトリには置かないでください。漏えいした場合は、同じページで失効させます。

環境変数に保存します。

```bash
export PIQLINE_API_KEY="piq_live_…"
```

## 2. キーを確認する

```bash tab="curl"
curl -s https://piqline.com/api/v1/workspace \
  -H "Authorization: Bearer $PIQLINE_API_KEY"
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/workspace", {
  headers: { Authorization: "Bearer " + process.env.PIQLINE_API_KEY },
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.get(
    "https://piqline.com/api/v1/workspace",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
)
data = response.json()
```

レスポンス:

```json
{
  "workspace": { "id": "b7a1c3e0-5d2f-4c8a-9e41-2f6d0a7b1c93", "name": "Atelier" },
  "key": {
    "id": "0d4e8f2a-71c6-4b3d-8a55-c9e2b6f10d47",
    "name": "Claude Code",
    "prefix": "piq_live_Ab12Cd",
    "scopes": ["read", "agents"]
  },
  "acting_as": {
    "user_id": "3c9a52e1-8b47-4d06-a2f3-71e0b5d4c689",
    "email": "vous@exemple.fr",
    "role": "owner"
  },
  "limits": {
    "requests_per_minute": 120,
    "agent_runs_per_minute": 10,
    "requests_per_day": 20000,
    "requests_today": 1
  }
}
```

`key.scopes` はキーで実行できる操作を、`limits` は残りの利用枠を示します。`401` は、キーがない、コピーを誤った、または失効したことを意味します。[エラー](/ja/docs/api/errors)を参照してください。

## 3. ツールを呼び出す (Call a tool)

ツールはアシスタントの機能の 1 つです。コーパスの読み取り、ライブ検索、書き込み、アクションがあります。この例では、直近 7 日間の収集量を読み取ります。

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/getCoverageStats \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"7d"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/getCoverageStats", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ period: "7d" }),
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/getCoverageStats",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={"period": "7d"},
)
data = response.json()
```

レスポンスにはツール名とその出力が入ります（ここでは短縮しています）。

```json
{
  "tool": "getCoverageStats",
  "output": {
    "period": "7d",
    "itemsTotal": 1842,
    "itemsPeriod": 214,
    "items24h": 37,
    "sources": 12,
    "byPlatform": [{ "platform": "rss", "items": 904, "items24h": 20 }]
  }
}
```

呼び出し可能な 92 個のツールと、そのスコープおよび入力は[カタログ](/ja/docs/api/tools#カタログ)にまとめています。

## 4. エージェントに質問する (Ask an agent)

エージェントは複数のツールを連鎖させ、自然言語で回答します。キーには `agents` スコープに加えて、エージェントが使うツールのスコープが必要です。

```bash tab="curl"
curl -s https://piqline.com/api/v1/agents/piqline \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Combien de sources suit ce workspace, et lesquelles sont en erreur ?"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/agents/piqline", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: "Combien de sources suit ce workspace, et lesquelles sont en erreur ?" }),
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/agents/piqline",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={"input": "Combien de sources suit ce workspace, et lesquelles sont en erreur ?"},
)
data = response.json()
```

レスポンス（短縮）:

```json
{
  "agent": "piqline",
  "status": "completed",
  "text": "Le workspace suit 12 sources, dont 2 en erreur : …",
  "tool_calls": [{ "tool": "listSources", "state": "output-available" }],
  "pending": []
}
```

詳しくは[エージェント](/ja/docs/api/agents)を参照してください。

## 5. MCP クライアントを接続する (Connect an MCP client)

Claude Code の場合:

```bash
claude mcp add --transport http piqline https://piqline.com/api/mcp \
  --header "Authorization: Bearer $PIQLINE_API_KEY"
```

その他のクライアントは [MCP サーバー](/ja/docs/api/mcp)で説明しています。

## 未対応の機能

- **Webhook。** お客様のシステムへのプッシュ通知はありません。新しく入ってくるデータを追うには、`getSignals` または `searchItems` を一定間隔でポーリングしてください。
- **公式 SDK。** [OpenAPI ドキュメント](https://piqline.com/api/v1/openapi.json)がすべてのルートを記述しています。クライアントジェネレーターを使うと、お使いの言語の SDK を生成できます。
- **OAuth サインイン。** 受け付けるのはキーのみです。claude.ai や ChatGPT のコネクターのように OAuth を必須とするものは、まだ接続できません。
- **一括エクスポート。** ツールは件数を制限した結果ページを返します（`searchItems` は最大 40 件）。
