# 빠른 시작

> 키 발급부터 첫 호출까지: 키를 만들고 도구, 에이전트 또는 MCP 클라이언트를 호출합니다.

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

Piqline API를 사용하면 스크립트와 에이전트가 워크스페이스에 접근할 수 있습니다. 대시보드 어시스턴트와 같은 도구와 같은 에이전트를 HTTP 또는 MCP(Model Context Protocol)로 사용합니다. 모든 호출은 하나의 워크스페이스에서, 키를 만든 멤버의 권한으로 실행됩니다.

## 필요한 것

- 소유자(owner) 또는 관리자(admin)로 속해 있는 Piqline 워크스페이스. 일반 멤버는 키 페이지를 읽기 전용으로만 볼 수 있습니다.
- HTTP 요청을 보낼 수 있는 도구(예제에서는 `curl`) 또는 MCP 클라이언트.

## 1. 키 만들기

1. [설정 → API 및 MCP](/settings/api)를 엽니다.
2. 키 이름을 입력하고, 스코프를 선택하고(`read`로 시작하세요), 만료 기간을 고릅니다.
3. **키 만들기**를 클릭한 다음 키를 복사합니다. 키는 한 번만 표시됩니다.

> **경고.** 키는 워크스페이스에서 사용자의 권한으로 동작합니다. 키는 시크릿 관리자나 환경 변수에 보관하고, 코드나 저장소에는 절대 넣지 마십시오. 키가 유출되면 같은 페이지에서 폐기합니다.

환경 변수에 저장합니다.

```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`은 키가 없거나, 잘못 복사했거나, 폐기되었다는 뜻입니다. [오류](/ko/docs/api/errors)를 참조하십시오.

## 3. 도구 호출하기

도구는 어시스턴트의 기능 하나입니다. 코퍼스 읽기, 실시간 검색, 쓰기, 실행이 있습니다. 이 예제는 최근 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개의 도구와 각 도구의 스코프 및 입력은 [카탈로그](/ko/docs/api/tools#카탈로그)에 있습니다.

## 4. 에이전트에게 질문하기

에이전트는 여러 도구를 연결해 자연어로 답합니다. 키에는 `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": []
}
```

자세한 내용은 [에이전트](/ko/docs/api/agents)를 참조하십시오.

## 5. MCP 클라이언트 연결하기

Claude Code의 경우:

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

다른 클라이언트는 [MCP 서버](/ko/docs/api/mcp)에서 다룹니다.

## 아직 제공되지 않는 기능

- **웹훅.** 시스템으로 푸시되는 데이터는 없습니다. 들어오는 내용을 추적하려면 `getSignals` 또는 `searchItems`를 일정한 간격으로 폴링하십시오.
- **공식 SDK.** [OpenAPI 문서](https://piqline.com/api/v1/openapi.json)가 모든 라우트를 설명합니다. 클라이언트 생성기로 사용하는 언어의 SDK를 만들 수 있습니다.
- **OAuth 로그인.** 키만 사용할 수 있습니다. claude.ai와 ChatGPT의 커넥터처럼 OAuth가 필요한 커넥터는 아직 연결할 수 없습니다.
- **일괄 내보내기.** 도구는 크기가 제한된 결과 페이지를 반환합니다(`searchItems`는 최대 40개 항목).
